Sign in
Batches

Create a batch

Create a batch of requests to run asynchronously. Each request is dispatched to its target route and results are made available for download when the batch completes.

post/batches

Headers

Exa-Beta'batches-2026-06-06' required

Required beta token for the Batch API.

Required beta token for the Batch API.

Request body

metadataobject

Caller-provided metadata stored with the batch.

Example request

{
  "requests": [
    {
      "customId": "row-1",
      "url": "/search"
    }
  ],
  "metadata": {
    "slack_channel_id": "C123ABC",
    "slack_thread_id": "1745444400.123456",
    "user_id": "U123ABC"
  }
}

Response

OK

idstring required

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

object'batch' required

The object type, always batch.

status'in_progress' | 'completed' | 'cancelling' | 'cancelled' | 'expired' required

Lifecycle status of the batch.

createdAtstring date-time required

When the batch was created.

expiresAtstring date-time nullable required

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

endedAtstring date-time nullable required

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

resultsUrlstring nullable 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.

metadataobject required

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

Example response

{
  "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8",
  "metadata": {
    "slack_channel_id": "C123ABC",
    "slack_thread_id": "1745444400.123456",
    "user_id": "U123ABC"
  }
}