Create a batch

Submit a batch of Exa API requests to run asynchronously.

POST /batches

Create a batch

cURL

curl --request POST \
  --url https://api.exa.ai/batches \
  --header 'Content-Type: application/json' \
  --header 'Exa-Beta: <exa-beta>' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "requests": [
    {
      "customId": "row-1",
      "method": "POST",
      "url": "/search",
      "body": {
        "query": "Latest AI infrastructure funding rounds"
      }
    },
    {
      "customId": "row-2",
      "method": "POST",
      "url": "/agent/runs",
      "body": {
        "query": "Summarize this week's vector database launches"
      }
    }
  ],
  "metadata": {
    "project": "weekly-digest"
  }
}
EOF

200

{
  "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8",
  "object": "batch",
  "status": "in_progress",
  "requestCounts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  },
  "createdAt": "2026-06-06T12:00:00.000Z",
  "expiresAt": "2026-06-13T12:00:00.000Z",
  "endedAt": null,
  "resultsUrl": null,
  "metadata": {
    "project": "weekly-digest"
  }
}

Each item in requests is a POST to /search or /agent/runs with a batch-unique customId. The same customId is returned in the results file so you can map output rows back to your input data. See the Batch API guide for the end-to-end workflow.

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 Batch API.

Available options: batches-2026-06-06

Body

application/json

requests · object[] · required

The requests to enqueue. Each customId must be unique within the batch.

Minimum array length: 1

Show child attributes

metadata · object

Caller-provided metadata stored with the batch.

Show child attributes

Example:

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

Response

200

application/json

OK

id · string · required

Batch ID. New batch IDs are returned with the batch_ prefix.

Example:

"batch_01j7x9v0m2n4p6q8r0s2t4v6w8"

object · string · required

The object type, always batch.

Allowed value: "batch"

status · enum<string> · required

Lifecycle status of the batch.

Available options: in_progress, completed, cancelling, cancelled, expired

requestCounts · object · required

Show child attributes

createdAt · string<date-time> · required

When the batch was created.

expiresAt · string<date-time> · required

When the batch expires, or null if it does not expire.

endedAt · string<date-time> · required

When the batch reached a terminal status, or null while it is still running.

resultsUrl · string | null · required

Short-lived presigned download URL for the batch results file (JSONL), or null until the batch completes. This is a direct object-store download link, not an API route; fetch it as-is and re-fetch the batch to mint a fresh URL once it expires.

metadata · object · required

Caller-provided key-value metadata for your own tracking.

Show child attributes

Example:

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