Exa Agent Runs

Hand a research task to an agent that works in the background.

POST https://api.aisa.one/apis/v1/exa/agent/runs

Submit an asynchronous research Agent run.

cURL

curl --request POST \
  --url https://api.aisa.one/apis/v1/exa/agent/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "query": "Summarize the main changes in RAG evaluation methods over the past year as a bullet list.",
  "outputSchema": {},
  "input": {
    "data": [
      "<unknown>"
    ],
    "exclusion": "<unknown>"
  },
  "effort": "<string>",
  "previousRunId": "<string>",
  "dataSources": [
    "<unknown>"
  ]
}
'

202

{
  "id": "iaj_01HZY8Q2M4K7N9V3T6W1X0B2C3",
  "object": "integration_async_job",
  "endpoint": "/apis/v1/exa/agent/runs",
  "status": "queued",
  "createdAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "pricing": {
    "currency": "USD",
    "authorizedMicrosUSD": 123,
    "finalMicrosUSD": 123,
    "billingMode": "flat_per_call"
  },
  "output": "<unknown>",
  "outputExpired": true,
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Hand a research task to an agent that works in the background. query and an Idempotency-Key are required; effort trades depth against time, outputSchema shapes the result, dataSources restricts where it looks, and previousRunId continues an earlier run. Asynchronous. Submitting returns HTTP 202 and a job envelope — id, object, endpoint, status, createdAt, completedAt, pricing, output, error — with output still null. Poll get_exa_agent_run until terminal; output then carries text, structured and grounding. A one-sentence question completed in well under a minute. Billed a flat $0.10 per run — pricing.billingMode is fixed_request, so unlike a Firecrawl crawl the price does not grow with what it finds. Use it when a report is the deliverable. For an answer you read in one sitting, post_exa_answer returns in about two seconds. Send a fresh Idempotency-Key per distinct task.

First time? Point any MCP client at https://mcp.aisa.one/mcp — Claude Code, Codex, Cursor, VS Code and the rest. Authorization is OAuth: the client opens a browser, you click Allow once, and there is no key to paste. The commands per client, and what each call costs, are on aisa.one/mcp.

Set this endpoint up in your agent →

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.

Show child attributes

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

202

application/json

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

Show child attributes

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.

Show child attributes