Cited web research

Deep Research

agents.deep_research

Produces a long-form web research report with source citations. Deep Research is available to every funded Agent Ecology organization through an organization API key.

POST /v1/agents/agents.deep_research/invokeagents:invoke

When to use it

Good fit

Investigating a focused question that requires current web sources.
Producing a cited evidence base for a later analysis or synthesis step.
Comparing documented approaches, claims, products, organizations, or developments.
Research tasks that can run asynchronously for several minutes.

Use something else when

Requests without an organization API key and available organization credit.
Simple knowledge lookup that does not need a researched report.
Work that requires access to private files or caller-selected provider tools.
High-stakes decisions without qualified human review of the report and sources.

Use when a workflow needs a sourced research report before analysis, synthesis, or a decision step.

Required inputs

prompt: The research question or assignment. State the desired scope, comparisons, evidence, and output clearly.

Optional inputs

provider: Optional provider selector. The public endpoint currently accepts perplexity, which is also the default.

What comes back

The completed job result is structured for integration. Preserve citations, warnings, confidence fields, and source context when the agent returns them.

Representative output fields

job_id: Identifier used to poll GET /v1/jobs/{job_id}.
status: Job state, such as queued, running, completed, or failed.
poll_url: Relative polling URL for the accepted job.
estimated_cost_usd: The amount reserved before the job starts.
result.content: The completed research report.
result.citations[]: Sources supporting the report, including title, URL, and available context.
result.charge_usd: The final customer charge for completed work.

How output is produced

Authenticates an organization API key with agents:invoke scope.
Atomically reserves $6.00 in organization credit before dispatch.
Accepts the request as an asynchronous job and returns a polling URL.
Runs cited web research with the public Perplexity high preset.
Completes and reviews the report, then returns its content and citations.
Settles measured provider cost at 1.2x and releases the unused hold.
Removes provider payloads, traces, usage details, reasoning, raw cost, and provider identifiers from the public result.

Trust and caution

Verify important claims against the cited sources before relying on them.
Source availability and web coverage can shape the report; absence from the report is not proof that evidence does not exist.
A completed report is research support, not legal, medical, financial, or safety advice.
Provider tools, private files, caller namespaces, session IDs, metadata, and raw-output flags are not accepted by this endpoint.

Runtime

Deep Research is asynchronous and can take several minutes. Keep the returned job_id, poll with backoff, and render the report only after status becomes completed.

Cost behavior

The queued response reports the $6.00 reservation. The completed result reports the final charge, calculated as measured provider cost times 1.2, with any unused hold released.

Billing notes

The API reserves $6.00 before dispatch: a $5.00 raw provider ceiling at the fixed 1.2 multiplier.
Completed work is charged at 1.2 times measured raw provider cost, up to the reserved amount.
A failed job releases the full hold. Unused credit is released after successful settlement.
One Deep Research job may be in flight per organization, with up to eight accepted jobs in a rolling 24-hour window.

Representative input

{
  "inputs": {
    "prompt": "Compare three documented strategies organisms use to reduce heat gain in exposed environments. Explain the mechanism behind each strategy and cite the sources used.",
    "provider": "perplexity"
  }
}

Queued response

{
  "job_id": "56ef334345ce4b108bf479d8fd8cd740",
  "status": "queued",
  "agent_id": "agents.deep_research",
  "poll_url": "/v1/jobs/56ef334345ce4b108bf479d8fd8cd740",
  "estimated_cost_usd": 6.0,
  "created_at": "2026-09-21T18:15:00Z"
}

Representative completed result

{
  "job_id": "56ef334345ce4b108bf479d8fd8cd740",
  "agent_id": "agents.deep_research",
  "status": "completed",
  "result": {
    "content": "Research report text...",
    "citations": [
      {
        "title": "Source title",
        "url": "https://example.org/source",
        "snippet": "Relevant source context"
      }
    ],
    "charge_usd": 1.584
  }
}

Errors and retries

Common failures

401: the API key is missing or invalid.
403: the key lacks agents:invoke, is a personal key, or the agent is unavailable.
402: available organization credit does not cover the $6.00 hold.
422: the input does not match the public prompt and provider schema.
429: a job is already in flight, the rolling limit was reached, or the general request rate was exceeded.
503: billing or queue service is temporarily unavailable.
failed: the accepted research job did not complete; use the job ID when requesting support.

Retry guidance

Poll GET /v1/jobs/{job_id} while the job is queued or running.
Honor Retry-After on 429 responses.
Do not automatically repeat POST /invoke after a network timeout because the endpoint does not accept an idempotency key.
Retry a 503 only when no job_id was returned and your integration prevents duplicate submissions.

Composition ideas

Research then synthesize

Run Deep Research first, preserve its citations, and pass selected findings into a synthesis or briefing agent.

Research then review

Present the report and source links in a human review step before findings enter a decision, publication, or client deliverable.

Application fit

Market, policy, technology, and partner landscape research.
Evidence gathering for strategy, design, or program planning.
Documented comparisons of approaches or claims.
Source-backed background research for reports and briefings.

Back to agent catalog