---
title: "List batches"
method: GET
path: "/v1/batches"
tags: ["Batches"]
---

# List batches

`GET /v1/batches`

## Request

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

Newest first. Test keys see test batches only.

## Query parameters

- `cursor` string
- `limit` integer
- `reference` string
- `status` 'canceled' | 'completed' | 'failed' | 'processing' | 'queued'
- `template_id` string

## Response `200`

- BatchList
  - `data` Batch[], required
    - `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
  - `has_more` boolean, required
  - `next_cursor` string, nullable
  - `object` 'list', required

## Other responses

- `400`: Unknown `status` or malformed `template_id`.
- `401`: Missing, invalid, expired or revoked credentials.
- `403`: Insufficient scope, IP not allowed, workspace suspended or scheduled for deletion, or email not verified.
- `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)