---
title: "Render a batch"
method: POST
path: "/v2/organizations/{organizationId}/templates/{externalId}/batches"
tags: ["Rendering"]
---

# Render a batch

`POST /v2/organizations/{organizationId}/templates/{externalId}/batches`

## Request

- Base URL: `https://api.pdfs.build`
- URL: `https://api.pdfs.build/v2/organizations/{organizationId}/templates/{externalId}/batches`
- Auth: HTTP bearer

Queues one async render per entry in `items`, up to 500, against one template and one version. The version is resolved when the batch is submitted, so promoting a channel mid-batch does not mix versions. The exception is a template that renders its live draft (nothing promoted yet, or a legacy auto-publish template): the draft is not pinned, so edits made mid-batch can reach later items. The whole batch is admitted against your monthly quota or rejected with `429`; a batch is never partially queued.

Items emit no per-render webhooks. On plans with webhooks (every paid plan), one `batch.completed` event goes to every enabled endpoint (or the `webhookIds` given) once every item has succeeded or failed. Poll `statusUrl` for per-item status and download links.

## Request body

- RenderBatchRequest
  - `items` object[], required
    - `data` object: Template data for this document, validated against the template schema when the item renders.
  - `webhookIds` string[]: Endpoints to notify with `batch.completed`. Omitted: every enabled endpoint. Empty: none.
  - `version` union: Which content to render. Omitted or `null` resolves through the `latest` channel, which follows promotions rather than in-progress edits. A positive integer pins a version number, `"draft"` renders the mutable working copy, and any other string names a channel.
    - integer
    - string

## Response `202`

Batch accepted and queued.

- RenderBatchAccepted
  - `id` string, required
  - `status` 'processing', required
  - `total` integer, required
  - `statusUrl` string, uri, required

## Other responses

- `400`: An invalid or unrenderable `version` selector, or `invalid_external_id`.
- `401`: Missing, invalid or expired API key.
- `402`: `api_renders_not_allowed_on_free`: REST renders need Starter or higher.
- `403`: The organization in the URL does not match the API key's organization.
- `404`: No template with that id is accessible to this key. Another user's draft is indistinguishable from a missing template.
- `413`: The request body exceeds 10 MB.
- `422`: `invalid_batch_size` (0 or more than 500 items) or `unknown_webhook_ids`.
- `429`: `render_quota_exceeded` — this billing period's render quota is used up. Upgrade or buy a top-up pack.
- `500`: Rendering failed for a reason that is not the template or the data. Safe to retry.

---

[API](https://skmtc.dev/pdfs/apis/pdfs-build-api.md) · [All operations](https://skmtc.dev/pdfs/apis/pdfs-build-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pdfs/apis/pdfs-build-api/revisions/1c7340b9521d?raw)