Batch Processing

The batch endpoint lets you submit multiple PDF URLs in a single API call. All conversions are processed asynchronously, and you can poll a single URL to monitor progress.

How it works

Send a POST to /v1/convert/batch with an array of PDF URLs.
The API returns a batchId and a pollUrl (status 202).
Poll GET /v1/batch/:batchId to check progress.
When all requests are complete, download each resultUrl.

Each URL in the batch consumes one request from your monthly quota.

Submit a batch

curl — batch request

curl -X POST https://api.pdfpipe.dev/v1/convert/batch \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      { "url": "https://example.com/invoice-1.pdf" },
      { "url": "https://example.com/invoice-2.pdf", "format": "text" },
      {
        "url": "https://example.com/report.pdf",
        "type": "attachment",
        "pages": "1-3",
        "metadata": { "department": "finance" }
      }
    ],
    "defaults": {
      "format": "json"
    }
  }'

Per-URL options: Each URL object can override format, type, pages, and metadata. The defaults object applies to any URL that doesn't specify its own value.

Batch response (202)

202 — Response

{
  "batchId": "batch_a1b2c3d4e5f6...",
  "requests": [
    { "requestId": "req_aaa...", "url": "https://example.com/invoice-1.pdf", "status": "queued" },
    { "requestId": "req_bbb...", "url": "https://example.com/invoice-2.pdf", "status": "queued" },
    { "requestId": "req_ccc...", "url": "https://example.com/report.pdf", "status": "queued" }
  ],
  "pollUrl": "/v1/batch/batch_a1b2c3d4e5f6..."
}

Poll for progress

curl — poll batch status

curl https://api.pdfpipe.dev/v1/batch/batch_a1b2c3d4e5f6... \
  -H "Authorization: Bearer pk_live_..."

200 — Batch status

{
  "batchId": "batch_a1b2c3d4e5f6...",
  "total": 3,
  "completed": 2,
  "failed": 0,
  "pending": 1,
  "requests": [
    { "requestId": "req_aaa...", "status": "complete", "resultUrl": "https://..." },
    { "requestId": "req_bbb...", "status": "complete", "resultUrl": "https://..." },
    { "requestId": "req_ccc...", "status": "processing" }
  ]
}

Poll every 5–10 seconds. When pending reaches 0, all jobs are done. Each completed request includes a presigned resultUrl.

Full Node.js example

Node.js

const response = await fetch("https://api.pdfpipe.dev/v1/convert/batch", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: pdfUrls.map(url => ({ url })),
    defaults: { format: "json" },
  }),
});

const { batchId, pollUrl } = await response.json();

// Poll until all complete
let batch;
do {
  await new Promise(r => setTimeout(r, 5000));
  const poll = await fetch(`https://api.pdfpipe.dev/v1${pollUrl}`, {
    headers: { "Authorization": "Bearer pk_live_..." },
  });
  batch = await poll.json();
  console.log(`Progress: ${batch.completed}/${batch.total}`);
} while (batch.pending > 0);

// Download all results
for (const req of batch.requests) {
  if (req.status === "complete") {
    const data = await fetch(req.resultUrl).then(r => r.json());
    console.log(`Result for ${req.requestId}:`, data);
  }
}

Batch size limits

The maximum number of URLs per batch depends on your tier:

Tier	Max batch size
Free	5 URLs
Starter	25 URLs
Pro	50 URLs
Business	100 URLs