Create a run

Create an asynchronous Agent run. By default, the API returns the run object immediately. Set Accept: text/event-stream to stream run lifecycle events until the run reaches a terminal status.

Accept'application/json' | 'text/event-stream'

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

Exa-Betastring

Comma-separated beta feature tokens for opting into experimental features.

Request body

querystring required

Natural-language question or instructions for the request.

systemPromptstring

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

outputSchemaobject nullable

JSON Schema for validated structured output in output.structured. Fields unsupported by evidence may be returned as null. Supports draft-07, 2019-09, and 2020-12 via $schema.

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

previousRunIdstring

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

metadataobject

Caller-provided metadata stored with the run.

Example request

{
  "query": "What are the most important AI infrastructure funding rounds announced this week?",
  "systemPrompt": "Prefer official sources and avoid duplicate results.",
  "previousRunId": "agent_run_01j7x9v0m2n4p6q8r0s2t4v6w8",
  "metadata": {
    "slack_channel_id": "C123ABC",
    "slack_thread_id": "1745444400.123456",
    "user_id": "U123ABC"
  }
}

Response

Agent run created

idstring required

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

object'agent_run' required

status'queued' | 'running' | 'completed' | 'failed' | 'cancelled' required

stopReason'schema_satisfied' | 'budget_reached' | 'error' | 'cancelled' required

createdAtstring date-time required

When the run was created

completedAtstring date-time nullable required

v1

Create a run

Headers

Request body

Example request

Response