> ## Documentation Index
> Fetch the complete documentation index at: https://pdfbase.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a batch

> Generate multiple PDFs in a single request. Each item can use HTML, URL, or a template.

## Phase

**Phase 1 (Launch)**

## Request

<ParamField body="items" type="array" required>
  Array of PDF generation requests. Each item follows the same schema as `POST /v1/pdfs`, plus an optional `template_id` + `data` for template-based generation.

  Max items per batch: plan-dependent (5 for Free, up to 2,000 for Scale).
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive webhook notifications for this batch. Overrides your account-level webhook for this job. Events: `batch.completed`, `batch.failed`, `batch.item.completed`, `batch.item.failed`.
</ParamField>

<ParamField body="parallel" type="integer" default="5">
  Max items to render concurrently within this batch. Capped by your plan's concurrency limit.
</ParamField>

<ParamField body="stop_on_failure" type="boolean" default="false">
  If `true`, stop processing remaining items when any item fails. Completed items are still available.
</ParamField>

<ParamField body="output" type="string" default="individual">
  How to deliver results:

  * `individual` — Each item gets its own PDF URL.
  * `merged` — All items are merged into a single PDF in order.
  * `zip` — All items are bundled into a ZIP file.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata attached to the batch job.
</ParamField>

## Item schema

Each item in the `items` array accepts:

```json theme={null}
{
  "html": "<h1>Invoice #1</h1>",
  "format": "a4",
  "metadata": { "invoice_id": "1" }
}
```

Or for template-based generation:

```json theme={null}
{
  "template_id": "tpl_abc123",
  "data": { "number": "INV-001", "customer": "Acme" },
  "metadata": { "invoice_id": "1" }
}
```

All fields from `POST /v1/pdfs` are supported per-item (`format`, `margin`, `compress`, etc.).

## Response

Batches are asynchronous. The response returns immediately with a `processing` status:

```json theme={null}
{
  "id": "bat_def456",
  "object": "batch",
  "status": "processing",
  "total_items": 50,
  "completed_items": 0,
  "failed_items": 0,
  "output": "individual",
  "parallel": 5,
  "stop_on_failure": false,
  "metadata": {},
  "created_at": "2026-05-19T11:00:00Z",
  "estimated_completion": "2026-05-19T11:02:30Z"
}
```

Poll `GET /v1/batches/:id` or listen for webhooks to track progress.

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pdfbase.dev/v1/batches \
    -H "Authorization: Bearer pk_live_xxx" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: monthly-invoices-2026-05" \
    -d '{
      "items": [
        {
          "template_id": "tpl_abc123",
          "data": { "number": "INV-042", "customer": "Acme", "total": "$500" }
        },
        {
          "template_id": "tpl_abc123",
          "data": { "number": "INV-043", "customer": "Globex", "total": "$750" }
        },
        {
          "template_id": "tpl_abc123",
          "data": { "number": "INV-044", "customer": "Initech", "total": "$200" }
        }
      ],
      "output": "individual",
      "parallel": 10,
      "webhook_url": "https://your-app.com/webhooks/batch-done"
    }'
  ```

  ```typescript TypeScript theme={null}
  const batch = await pdfbase.batches.create({
    items: invoices.map(inv => ({
      template_id: 'tpl_abc123',
      data: { number: inv.number, customer: inv.customer, total: inv.total },
      metadata: { invoice_id: inv.id },
    })),
    output: 'merged',
    parallel: 10,
  })

  // Poll for completion
  const result = await pdfbase.batches.poll(batch.id) // convenience method
  ```
</CodeGroup>