EXexa
Agent

Create a run

Changed on

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.

post/agent/runs

Request

  • Base URL
    https://api.exa.ai
  • URL
    https://api.exa.ai/agent/runs
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Headers

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.

effort'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'auto' | 'ultra'

Cost and reasoning effort preference for the run. auto lets Exa choose the appropriate effort. ultra is the highest-effort tier for work where completeness and thoroughness matter more than latency or cost, including large list building, deep multi-source research, and criteria that are hard to verify.

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.

previousRunIdstring

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

metadataobject

Caller-provided metadata stored with the run.

userIdentifierstring nullable

An opaque ID your platform assigns to the end user this request is made for, such as a UUID. Lets Exa attribute usage to that end user rather than your whole team. Must not contain personal information such as an email address, phone number, username, or name. Hash such values before sending them. 1 to 64 characters: letters, digits, underscores, and hyphens. Retained even when your team has Zero Data Retention enabled. Does not affect results.

Example request

{
  "userIdentifier": "7f3a9c52-1d4e-4b8a-9e60-2c5d8a1f0b37"
}

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
createdAtstring date-time required

When the run was created

completedAtstring date-time nullable required

Changes

  • 9fa4de48c6afRevision changes
    • info

      added the required property to the response with the status

  • f21ac0e3acccRevision changes
    • breaking

      the //// response's property type changed from string to no type for status

    • breaking

      the / response's property type changed from integer to number for status

    • breaking

      the / response's property type changed from integer to number for status

    • breaking

      the / response's property type changed from integer to number for status

    • info

      added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 subschema #7 subschema #8 subschema #9 to the //// response property anyOf list for the response status

    • info

      removed the budget_reached enum value from the //// response property for the response status

    • info

      removed the cancelled enum value from the //// response property for the response status

    • info

      removed the error enum value from the //// response property for the response status

    • info

      removed the schema_satisfied enum value from the //// response property for the response status

    • info

      removed the stopped enum value from the //// response property for the response status

    • info

      removed the time_limit_reached enum value from the //// response property for the response status