Create a run

Create an asynchronous Agent run. The response returns the run object immediately unless you request server-sent events.

POST /agent/runs

cURL

Create a run

curl -s -X POST "https://api.exa.ai/agent/runs" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -H "Exa-Beta: agent-2026-05-07" \
  -d '{
    "query": "What are the most important AI infrastructure funding rounds announced this week?"
  }'

200

{
  "id": "agent_run_01j7x9v0m2n4p6q8r0s2t4v6w8",
  "object": "agent_run",
  "status": "running",
  "stopReason": null,
  "createdAt": "2026-05-07T18:31:00.000Z",
  "completedAt": null,
  "request": {
    "query": "What are the most important AI infrastructure funding rounds announced this week?"
  },
  "output": {
    "text": "",
    "structured": null,
    "grounding": []
  },
  "usage": {
    "agentComputeUnits": 0,
    "searches": 0,
    "emails": 0,
    "phoneNumbers": 0
  },
  "costDollars": {
    "total": 0,
    "agentCompute": 0,
    "search": 0,
    "emails": 0,
    "phoneNumbers": 0
  }
}

Exa Agent is in beta. It requires Exa-Beta: agent-2026-05-07 on every request.

Create a run with a natural-language query. Add outputSchema for validated structured JSON, input.data for rows to process, input.exclusion for records or entities to avoid, or previousRunId to continue from a completed run.

Set Accept: text/event-stream to stream run events as the run is created, started, and completed.

Get your Exa API key

Authorizations

apiKeybearer

x-api-key · string · header · required

Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer .

Headers

Exa-Beta · enum<string> · required

Required beta token for the Agent.

Available options: agent-2026-05-07

Accept · enum<string>

Set to text/event-stream to receive server-sent events.

Available options: application/json, text/event-stream

Body

application/json

query · string · required

Natural-language question or instructions for the request.

Minimum string length: 1

Example:

"What are the most important AI infrastructure funding rounds announced this week?"

systemPrompt · string

Additional instructions that guide generated output or agent behavior. Use this for source preferences, novelty constraints, duplication constraints, or other behavior guidance.

Example:

"Prefer official sources and avoid duplicate results."

input · object

Records to process and records or entities to exclude from the answer.

Show child attributes

outputSchema · object

JSON Schema for validated structured output in output.structured. Supports draft-07, 2019-09, and 2020-12 via $schema.

Show child attributes

effort · enum<string> · default: auto

Cost and reasoning effort preference for the run. auto lets Exa choose the appropriate effort.

Available options: low, medium, high, xhigh, auto

previousRunId · string

Completed run ID to continue from. Must belong to the same team.

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9_.:-]+$

Example:

"agent_run_01j7x9v0m2n4p6q8r0s2t4v6w8"

metadata · object

Caller-provided metadata stored with the run.

Show child attributes

Example:

{
  "slack_channel_id": "C123ABC",
  "slack_thread_id": "1745444400.123456",
  "user_id": "U123ABC"
}

budget · object · deprecated

Accepted for compatibility and currently ignored.

Show child attributes

Response

200

application/json

Agent run created

id · string · required

Agent run ID. New run IDs are returned with the agent_run_ prefix.

Required string length: 1 - 200

Pattern: ^[A-Za-z0-9_.:-]+$

Example:

"agent_run_01j7x9v0m2n4p6q8r0s2t4v6w8"

object · string · required

Allowed value: "agent_run"

status · enum<string> · required

Available options: queued, running, completed, failed, cancelled

stopReason · enum<string> | null · required

Why the run stopped. null while the run is queued or running.

Available options: schema_satisfied, budget_reached, error, cancelled

createdAt · string<date-time> · required

When the run was created

completedAt · string<date-time> · required

request · object · required

Canonicalized request fields stored with the run.

Show child attributes

output · object · required

Show child attributes

usage · object · required

Show child attributes

costDollars · object · required

Show child attributes