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: queued, running, completed, failed, or canceled.
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. On a canceled job, result is exactly {"charge_usd": <number>} when provider work consumed before the cancellation was charged.

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.
Legacy namespace and session_id string hints are accepted but ignored. Omit them in new integrations; the organization API key determines identity.
The pubmed provider, max_results, provider tools, private files, metadata, and raw-output flags are rejected before billing or dispatch. This endpoint does not provide PubMed bibliographic search.

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.
DELETE /v1/jobs/{job_id} cancels a queued or running job and stops the provider run. Provider work consumed before the cancellation is charged: the canceled job then carries result exactly as {"charge_usd": <number>}, and that result appears once the charge settles. A canceled job with nothing consumed has no result and no charge.
One Deep Research job may be in flight per organization.

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 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.
Cancel with DELETE /v1/jobs/{job_id}, then poll the job until it reports canceled. A 409 means the job had already reached a terminal state.

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