Batches

Cancel a batch

Request cancellation of a batch. The batch stops scheduling new requests and drains in-flight work before settling to cancelled. Cancelling a batch that is already cancelling or cancelled is idempotent and returns the batch unchanged. A batch that has already reached a terminal status (completed or expired) cannot be cancelled and the request fails with a 409.

post/batches/{id}/cancel

Path parameters

idstring required

Batch ID.

Example:batch_01j7x9v0m2n4p6q8r0s2t4v6w8

Batch ID.

Headers

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

Required beta token for the Batch API.

Response

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"
  }
}