> ## 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.

# Batch Processing

> Generate hundreds of PDFs in a single API call.

## When to use batches

Use the batch endpoint when you need to generate more than a handful of PDFs at once:

* Monthly invoice runs
* Bulk certificate generation
* Report exports
* Data migration (re-rendering documents)

## Basic batch

```bash theme={null}
curl -X POST https://api.pdfbase.dev/v1/batches \
  -H "Authorization: Bearer pk_live_xxx" \
  -H "Idempotency-Key: invoices-2026-05" \
  -d '{
    "items": [
      { "template_id": "tpl_abc123", "data": { "number": "INV-001", "customer": "Acme" } },
      { "template_id": "tpl_abc123", "data": { "number": "INV-002", "customer": "Globex" } },
      { "template_id": "tpl_abc123", "data": { "number": "INV-003", "customer": "Initech" } }
    ]
  }'
```

## Output modes

### individual (default)

Each item produces its own PDF with its own URL:

```json theme={null}
{
  "results": [
    { "index": 0, "pdf_id": "pdf_a", "url": "..." },
    { "index": 1, "pdf_id": "pdf_b", "url": "..." }
  ]
}
```

### merged

All items are combined into a single PDF in order:

```json theme={null}
{ "merged_pdf": { "id": "pdf_merged", "url": "...", "pages": 100 } }
```

Useful for: print-ready batch documents, combined monthly reports.

### zip

All items are bundled into a downloadable ZIP:

```json theme={null}
{ "zip_url": "...", "zip_bytes": 3800000 }
```

Useful for: bulk downloads, email attachments.

## Tracking progress

Batches are async. Poll or use webhooks:

### Polling

```typescript theme={null}
const batch = await pdfbase.batches.create({ items: [...] })

// SDK convenience method — polls every 2s, returns when done
const result = await pdfbase.batches.poll(batch.id, {
  interval: 2000,
  timeout: 300000,
})
```

### Webhooks

```json theme={null}
{
  "webhook_url": "https://your-app.com/webhooks/batch-done",
  "items": [...]
}
```

Events:

* `batch.item.completed` — fired for each item (useful for progress bars)
* `batch.completed` — fired when all items are done
* `batch.failed` — fired if the batch fails

## Error handling

By default, a failed item doesn't stop the batch. The batch completes with partial results:

```json theme={null}
{
  "status": "completed",
  "total_items": 50,
  "completed_items": 48,
  "failed_items": 2,
  "results": [
    { "index": 0, "status": "completed", "pdf_id": "pdf_a", "url": "..." },
    { "index": 7, "status": "failed", "error": { "code": "timeout_exceeded" } },
    ...
  ]
}
```

Set `stop_on_failure: true` to abort remaining items on the first failure.

## Concurrency

The `parallel` parameter controls how many items render simultaneously:

```json theme={null}
{ "parallel": 10, "items": [...] }
```

Higher parallelism = faster completion, but uses more of your concurrency quota. If your plan allows 20 concurrent renders and you set `parallel: 20`, the batch monopolizes your capacity — other API calls will queue.

## Billing

Each completed item in a batch costs 1 credit. Failed items are free. A 50-item batch with 2 failures costs 48 credits.