Skip to main content
POST
Submit an asynchronous research Agent run.
Submit a natural-language research 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
  1. SubmitPOST /apis/v1/exa/agent/runs with the research body and a required Idempotency-Key header. On success you get back 202 Accepted, a Location header pointing at the job resource (/apis/v1/exa/agent/runs/{jobId}), and a job object whose status starts as queued. Re-submitting with the same key and the same request body returns the original run; the same key with a different body returns 409 idempotency_conflict.
  2. PollGET /apis/v1/exa/agent/runs/{jobId} and repeat until status is terminal: completed, failed, or cancelled. When completed, the research result is in output. The provider supports polling only — there is no webhook or SSE callback.
  3. ListGET /apis/v1/exa/agent/runs (optional status filter, paginated) to page through your runs.
  4. CancelPOST /apis/v1/exa/agent/runs/{jobId}/cancel to request cancellation; cancelled runs are not billed.
Supply an 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

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Unique key (1 to 191 characters) that makes the submit idempotent. Re-submitting with the same key and request fingerprint returns the original run.

Maximum string length: 191

Body

application/json
query
string
required

The natural-language research query.

Example:

"Summarize the main changes in RAG evaluation methods over the past year as a bullet list."

outputSchema
object

JSON Schema used to validate the structured output.

input
object

Row-processing input: rows to process and exclusions.

effort
string

Compute/depth tier for the run.

previousRunId
string

Continue from a previously completed run.

dataSources
any[]

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).

id
string

Unique AIsa job identifier. Use it to poll, list, or cancel the job.

Example:

"iaj_01HZY8Q2M4K7N9V3T6W1X0B2C3"

object
string

Always "integration_async_job".

Example:

"integration_async_job"

endpoint
string

The submit endpoint this job belongs to.

Example:

"/apis/v1/exa/agent/runs"

status
enum<string>

Customer-facing lifecycle status. queued and running are non-terminal; completed, failed, and cancelled are terminal.

Available options:
queued,
running,
completed,
failed,
cancelled
createdAt
string<date-time>

When the job was accepted.

completedAt
string<date-time> | null

When the job reached a terminal status. Null while the job is still queued or running.

pricing
object
output
any | null

Job result payload. Present only once status is completed. For Agent Runs this is the structured research result.

outputExpired
boolean

True when the result has been retained past its retention window and is no longer retrievable.

error
object | null

Present when status is failed. Null otherwise.