Skip to main content
GET
Poll a retrieval agent run

Notes

  • Poll with the run_id returned by Dispatch a Retrieval Agent run. status progresses queuedrunningcompleted / failed; the result (a RetrievalAgentResult) is populated once status is completed.
  • The result carries answer, cards, citations, and — when the request supplied an output_schema — the structured_output* fields. There is no web_results field; web and Tako sources alike land in the top-level citations registry.
  • To resume or tail the run as a live Server-Sent Events stream, send Accept: text/event-stream. Use starting_after (or the Last-Event-ID header) to replay only events whose seq is greater than a value you’ve already seen. See the Retrieval Agent guide.

Authorizations

X-API-Key
string
header
required

Path Parameters

run_id
string
required

The run ID from the POST /v1/agent/retrieval/runs response.

Query Parameters

starting_after
integer

SSE resume cursor (Accept: text/event-stream only). The stream replays events with seq greater than this value. It is equivalent to the Last-Event-ID header.

Required range: x >= 0

Response

Current state of the agent run. With Accept: text/event-stream, the response replays and then follows the run as an SSE stream of RetrievalAgentStreamEnvelope events. Use starting_after or Last-Event-ID to resume. If the stream ends without an agent_result event, poll this endpoint with Accept: application/json for the terminal status.

The retrieval-agent run resource returned by dispatch (202) and poll (GET).

run_id
string
required
status
enum<string>
required
Available options:
queued,
running,
completed,
failed
created_at
string
required
object
string
default:agent.retrieval.run
Allowed value: "agent.retrieval.run"
thread_id
string | null
completed_at
string | null
result
RetrievalAgentResult · object | null

Final retrieval-agent output. answer is markdown prose with [n] citation markers. cards reuse the sibling TakoCard. citations is the unified top-level registry for data and web sources — there is no web_results field. metadata carries definitions, assumptions, and methodology. The structured_output_* fields carry the caller-shaped output_schema result; they are present only if the request supplied output_schema. See each field's description for the exact presence rules.

error
ErrorObject · object | null
usage
Usage · object | null

Usage for one metered request. total_cost_usd is always present (the total quoted charge). compute and data are the additive breakdown; each appears only where it applies. total_cost_usd always equals the sum of the components that appear.

request
RetrievalAgentRunRequest · object | null

Request body for POST /v1/agent/retrieval/runs.