EXexa
Batches

Create a batch

Changed on

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

Request

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

Headers

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

Required beta token for the Batch API.

Request body

metadataobject

Caller-provided metadata stored with the batch.

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 download URL for the batch results file (JSONL), or null until the batch completes. Fetch it directly, without an API key. Retrieve the batch again for a fresh URL after it expires.

metadataobject required

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

Changes

  • 9836dac5075aRevision changes
    • info

      added the non-success response with the status

  • 67abccbd77b6Revision changes
    • warning

      deleted the header request parameter Exa-Version

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status