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

# Cancel a batch

`POST /v1/batches/{batch_id}/cancel`

## Request

- Base URL: `https://api-eu.dynamicdocumentapi.com`
- URL: `https://api-eu.dynamicdocumentapi.com/v1/batches/{batch_id}/cancel`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Items not released yet are canceled; released renders are canceled when a worker picks them up (items already rendering may still finish and are counted). The batch is `canceled` at once and `batch.completed` fires. Canceled items are not billed.

## Path parameters

- `batch_id` string, required

## Headers

- `Idempotency-Key` string

## Response `200`

- Batch
  - `canceled` integer
  - `combine` object
    - `merged_pdf` boolean
    - `zip` boolean
    - `zip_filename` string, nullable
  - `completed_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `emails` BatchEmailCounts: The newest email of each item and rule, by status (a resend replaces the email it repeats): `pending` includes `sending` and `retrying`, `sent` includes `sandboxed`.
    - `canceled` integer, required
    - `failed` integer, required
    - `pending` integer, required
    - `sent` integer, required
    - `skipped` integer, required
    - `unknown` integer, required
  - `error` object, nullable: Set when a requested combined file failed, which fails the batch: that file's error (the ZIP's first). `null` otherwise. `item_files_expired`: the files of succeeded items expired or were deleted before they could be combined; the combined files hold every succeeded item or none.
    - `code` string, required
    - `items` integer[]: `item_files_expired`: indexes of the items whose files are gone, ascending, at most 100.
    - `message` string, required
  - `failed` integer
  - `files` BatchFile[], required
    - `bytes` integer, required
    - `content_type` string, required
    - `expires_at` string, date-time, nullable: When the hosted file is deleted.
    - `file_id` string, required
    - `filename` string, required
    - `kind` 'zip' | 'merged_pdf', required
    - `pages` integer, nullable: Merged PDF only.
    - `url` string, uri: Signed URL (omitted when not hosted).
    - `url_expires_at` string, date-time
  - `id` string, required
  - `metadata` object
  - `object` 'batch', required
  - `paused` object, nullable: Set while the batch waits for renders: no item is released until a render pack, a plan change or the next cycle makes renders available again, then the batch resumes on its own (checked about once a minute). Items in flight finish normally; canceling works as usual. `null` otherwise.
    - `reason` 'render_limit_reached', required
    - `since` string, date-time, required
  - `pending` integer: Items without a final status yet.
  - `progress` number: Finished items ÷ total.
  - `reference` string, nullable
  - `status` 'queued' | 'processing' | 'completed' | 'failed' | 'canceled', required
  - `succeeded` integer
  - `template_id` string
  - `template_version` integer, nullable: Version number rendered.
  - `test` boolean, required
  - `total` integer, required

## Other responses

- `401`: Missing, invalid, expired or revoked credentials.
- `403`: Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified.
- `404`: Batch not found.
- `409`: `conflict`: the batch already finished.
- `429`: Rate limited (`Retry-After`).

---

[API](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api.md) · [All operations](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dynamicdocumentapi/apis/dynamic-document-api/revisions/0f14bc0000f4?raw)