Skip to main content
POST
/
agent
/
runs
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?"
  }'
{
  "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
  }
}

Documentation Index

Fetch the complete documentation index at: https://exa.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
x-api-key
string
header
required

Your Exa API key.

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 instructions for the run.

Minimum string length: 1
​
systemPrompt
string

Additional behavior guidance for the agent.

​
input
object

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

​
outputSchema
object

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

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

​
budget
object
deprecated

Accepted for compatibility and currently ignored.

Response

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
​
completedAt
string<date-time> | null
required
​
request
object
required

Canonicalized request fields stored with the run.

​
output
object
required
​
usage
object
required
​
costDollars
object
required