---
title: "Cancel a batch"
method: POST
path: "/batches/{id}/cancel"
tags: ["Batches"]
---

# Cancel a batch

`POST /batches/{id}/cancel`

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.

## Path parameters

- `id` string, required — Batch ID.

## Headers

- `Exa-Beta` 'batches-2026-06-06', required — Required beta token for the Batch API.

## Response `200`

OK

- Batch
  - `id` string, 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.
  - `requestCounts` BatchRequestCounts, required
    - `total` integer, required — Total requests in the batch.
    - `completed` integer, required — Requests that have completed successfully.
    - `failed` integer, required — Requests that have failed.
  - `createdAt` string, date-time, required — When the batch was created.
  - `expiresAt` string, date-time, nullable, required — When the batch expires, or `null` if it does not expire.
  - `endedAt` string, date-time, nullable, required — When the batch reached a terminal status, or `null` while it is still running.
  - `resultsUrl` string, 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.
  - `metadata` object, required — Caller-provided key-value metadata for your own tracking.

## Other responses

- `400` — The request body or query parameters failed validation.
- `401` — The API key is missing or invalid.
- `404` — The requested resource does not exist.
- `409` — The request conflicts with the current state of the resource.
- `500` — An unexpected error occurred while processing the request.

## Changes

- **2026-08-27** `67abccbd77b6` — 1 warning, 4 info
  - deleted the `header` request parameter `Exa-Version`
  - added the non-success response with the status `400`
  - added the non-success response with the status `404`
  - added the non-success response with the status `409`
  - …1 more
- **2026-08-26** `bcc51991b48a` — 1 info
  - added the new optional `header` request parameter `Exa-Version`
- **2026-08-25** `659cf16a7325` — 1 info
  - added the non-success response with the status `401`
- **2026-08-24** `cebbdd9640af` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/exa/apis/exa-public-api/changes/batches/:id/cancel/post.md)

---

[API](https://skmtc.dev/exa/apis/exa-public-api.md) · [All operations](https://skmtc.dev/exa/apis/exa-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/exa/exa-public-api/revisions/aa8be0299043/schema)