Exa Agent Runs
Submit a research task to the Exa Agent as an asynchronous job — submit, then poll the run for status and results.
query and the Exa Agent runs it in the background, returning a structured result. Because deep research takes time, Agent Runs is an asynchronous job: you submit the run and then poll it for status and results.
Lifecycle
- Submit —
POST /apis/v1/exa/agent/runswith the research body and a requiredIdempotency-Keyheader. On success you get back202 Accepted, aLocationheader pointing at the job resource (/apis/v1/exa/agent/runs/{jobId}), and a job object whosestatusstarts asqueued. Re-submitting with the same key and the same request body returns the original run; the same key with a different body returns409 idempotency_conflict. - Poll —
GET /apis/v1/exa/agent/runs/{jobId}and repeat untilstatusis terminal:completed,failed, orcancelled. Whencompleted, the research result is inoutput. The provider supports polling only — there is no webhook or SSE callback. - List —
GET /apis/v1/exa/agent/runs(optionalstatusfilter, paginated) to page through your runs. - Cancel —
POST /apis/v1/exa/agent/runs/{jobId}/cancelto request cancellation; cancelled runs are not billed.
outputSchema to validate the structured output, effort to trade depth for latency, previousRunId to continue a prior run, and input/dataSources for row-processing and Exa Connect sources. Billed at a flat $0.10 per run. For a single-shot cited answer instead of a multi-step run, use post_exa-answer.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Unique key (1 to 191 characters) that makes the submit idempotent. Re-submitting with the same key and request fingerprint returns the original run.
191Body
The natural-language research query.
"Summarize the main changes in RAG evaluation methods over the past year as a bullet list."
JSON Schema used to validate the structured output.
Row-processing input: rows to process and exclusions.
Compute/depth tier for the run.
Continue from a previously completed run.
Third-party data sources (Exa Connect) the Agent is granted access to.
Response
Research run accepted. The Location header points at the job resource; poll it until terminal.
An asynchronous integration job. Returned by the submit call (HTTP 202) and by the poll/detail call. Poll the job by its id until status is a terminal value (completed, failed, or cancelled).
Unique AIsa job identifier. Use it to poll, list, or cancel the job.
"iaj_01HZY8Q2M4K7N9V3T6W1X0B2C3"
Always "integration_async_job".
"integration_async_job"
The submit endpoint this job belongs to.
"/apis/v1/exa/agent/runs"
Customer-facing lifecycle status. queued and running are non-terminal; completed, failed, and cancelled are terminal.
queued, running, completed, failed, cancelled When the job was accepted.
When the job reached a terminal status. Null while the job is still queued or running.
Job result payload. Present only once status is completed. For Agent Runs this is the structured research result.
True when the result has been retained past its retention window and is no longer retrievable.
Present when status is failed. Null otherwise.