Queued rendering

When to queue instead

The direct endpoint answers when the document is ready, which is the simplest thing as long as the caller can wait. Queue the work when the document is long, when you produce many at once, or when the caller is a web request that must not sit open: the answer comes back at once with a queueId and the work continues behind it.

Queue the request for long documents and bulk jobs. The response returns immediately and you follow the job at its statusUrl.

Queue order

Queue priority comes from your plan and is not a separate queue: a job is treated as if it arrived earlier in proportion to its priority. That has two consequences — a higher-priority job overtakes one queued at the same moment, and a waiting job never waits forever. The worst-case wait is a number you can compute; with today’s values a Free job waits at most 54 minutes and a Max job does not wait at all.

curl -X POST https://api.pdfgine.com/api/v1/documents/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateCode": "invoice", "format": "pdf", "data": { } }'

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "queued",
  "statusUrl": "/api/v1/async-jobs/queue_ea464b42...",
  "documentId": null,
  "createdAt": "2026-08-28T13:23:45+00:00"
}

curl https://api.pdfgine.com/api/v1/async-jobs/queue_ea464b42... \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

Add a webhookUrl to the request and a signed notification is delivered when the job finishes, so you never have to poll.

What a finished job looks like

Read the job at its statusUrl. While it runs status is queued or running; when it is done documentId and result are filled in.

{
  "queueId": "queue_ea464b42458e4768ab26d59a88f3291d",
  "status": "succeeded",
  "attemptCount": 1,
  "documentId": "doc_a96063f5dcd5400286ce9b3be9b0595b",
  "result": {
    "downloadUrl": "/api/v1/documents/doc_a96063f5dcd5400286ce9b3be9b0595b/download/pdf",
    "pageCount": 12
  },
  "failureCode": null,
  "createdAt": "2026-08-28T13:23:45+00:00",
  "completedAt": "2026-08-28T13:23:52+00:00"
}

A failed job answers with status failed and a failureCode that says why; the same codes are listed on the errors page.

What usually goes wrong

• The queue answers 202 with queueId and no document. documentId stays null until the job finishes; reading it right away and treating null as a failure is the most common mistake here.
• Polling every second wastes your rate limit. Poll a few seconds apart, or send a webhookUrl and do not poll at all.
• status failed is a finished job, not a pending one. Read failureCode and fix the input; the job will not start again by itself.
• A webhook notification is signed. Verify the signature before trusting it - the webhooks page shows how - and answer 2xx, otherwise it is delivered again.
• A queued document costs the same pages as a direct one. The queue changes when the work happens, not what it costs.