Render a batch asynchronously

For batches you don’t want to hold an HTTP request open for. The call returns immediately with a jobId; Pagr renders in the background and POSTs a webhook as each document finishes, plus one final callback when the job ends. If you can’t host a public endpoint, poll the job-status endpoint instead — it exposes the same information.

Endpoints

POST /v1/render/{templateId}/async
POST /v1/render/{templateId}/versions/{version}/async
GET  /v1/render/jobs/{jobId}

The two POST forms enqueue against the latest published version or a specific one. The GET form polls a job’s status and is scoped to the calling organisation — another tenant’s job returns 404.

Example

Python

import asyncio
from pagr import PagrApiClient

async def main():
    async with PagrApiClient("pagr_prod_xxxxxxxx") as client:
        job = await client.enqueue_batch_render(
            "8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90",
            [
                {"Title": "Acme Q3 Invoice", "Amount": 42},
                {"Title": "Acme Q4 Invoice", "Amount": 58},
            ],
            callback_url="https://your-app.example/pagr/callback?token=s3cr3t",
        )
        print(job.job_id, job.requested_count, job.state)   # state == QUEUED

        # Poll until terminal. wait_for_job wraps the "while not status.done" loop.
        status = await client.wait_for_job(job.job_id, poll_interval=2.0, timeout=300)
        print(status.state, status.status,
              f"{status.rendered_count}/{status.requested_count}")
        for issue in status.issues:
            print(issue)

asyncio.run(main())

TypeScript

import { PagrApiClient } from 'pagr';

const client = new PagrApiClient('pagr_prod_xxxxxxxx');

const job = await client.enqueueBatchRender(
  '8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90',
  [
    { Title: 'Acme Q3 Invoice', Amount: 42 },
    { Title: 'Acme Q4 Invoice', Amount: 58 },
  ],
  'https://your-app.example/pagr/callback?token=s3cr3t',
);
console.log(job.jobId, job.requestedCount, job.state);   // 'queued'

const status = await client.waitForJob(job.jobId, { pollIntervalMs: 2000, timeoutMs: 300_000 });
console.log(status.state, status.status, `${status.renderedCount}/${status.requestedCount}`);

Java

import org.example.PagrApiClient;
import org.example.models.RenderJob;
import org.example.models.RenderJobStatus;
import java.time.Duration;
import java.util.List;
import java.util.UUID;

try (PagrApiClient client = new PagrApiClient("pagr_prod_xxxxxxxx")) {

    RenderJob job = client.enqueueBatchRender(
        UUID.fromString("8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90"),
        List.of(
            "{\"Title\": \"Acme Q3 Invoice\", \"Amount\": 42}",
            "{\"Title\": \"Acme Q4 Invoice\", \"Amount\": 58}"),
        "https://your-app.example/pagr/callback?token=s3cr3t");

    System.out.println(job.getJobId() + " — " + job.getState());

    RenderJobStatus status = client.waitForJob(
        job.getJobId(), Duration.ofSeconds(2), Duration.ofMinutes(5));
    System.out.println(status.getState() + " / " + status.getStatus()
        + " — " + status.getRenderedCount() + "/" + status.getRequestedCount());
}

C#

using Pagr.Sdk;

using var client = new PagrApiClient("pagr_prod_xxxxxxxx");

var job = await client.EnqueueBatchRenderAsync(
    Guid.Parse("8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90"),
    new[]
    {
        new { Title = "Acme Q3 Invoice", Amount = 42 },
        new { Title = "Acme Q4 Invoice", Amount = 58 },
    },
    callbackUrl: "https://your-app.example/pagr/callback?token=s3cr3t");

Console.WriteLine($"{job.JobId} — {job.RequestedCount} doc(s) — {job.State}");

var status = await client.WaitForJobAsync(
    job.JobId, pollInterval: TimeSpan.FromSeconds(2), timeout: TimeSpan.FromMinutes(5));
Console.WriteLine($"{status.State} / {status.Status} — {status.RenderedCount}/{status.RequestedCount}");

Ruby

require "pagr"

client = Pagr::Client.new("pagr_prod_xxxxxxxx")

job = client.enqueue_batch_render(
  "8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90",
  [
    { "Title" => "Acme Q3 Invoice", "Amount" => 42 },
    { "Title" => "Acme Q4 Invoice", "Amount" => 58 },
  ],
  "https://your-app.example/pagr/callback?token=s3cr3t",
)
puts "#{job.job_id} — #{job.requested_count} doc(s) — #{job.state}"

status = client.wait_for_job(job.job_id, poll_interval: 2.0, timeout: 300)
puts "#{status.state} / #{status.status} — #{status.rendered_count}/#{status.requested_count}"

C++

#include "pagr/PagrApiClient.hpp"

pagr::PagrApiClient client("pagr_prod_xxxxxxxx");

std::vector<std::string> documents = {
    R"({"Title": "Acme Q3 Invoice", "Amount": 42})",
    R"({"Title": "Acme Q4 Invoice", "Amount": 58})",
};

auto job = client.enqueue_batch_render(
    std::string("8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90"),
    documents,
    "https://your-app.example/pagr/callback?token=s3cr3t");

std::cout << job.job_id << " — " << job.requested_count << " doc(s)\n";

auto status = client.wait_for_job(
    job.job_id, std::chrono::seconds(2), std::chrono::minutes(5));
std::cout << status.rendered_count << "/" << status.requested_count << "\n";

cURL

# 1. Enqueue
curl -X POST "https://api.pagr.eu/v1/render/8bec66ff-6f3d-4c1e-9a2b-1f0e5d7c4a90/async" \
  -H "Authorization: Bearer pagr_prod_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "Title": "Acme Q3 Invoice", "Amount": 42 },
      { "Title": "Acme Q4 Invoice", "Amount": 58 }
    ],
    "callbackUrl": "https://your-app.example/pagr/callback?token=s3cr3t"
  }'
# → 202 { "jobId": "…", "requestedCount": 2, "state": "queued" }

# 2. Poll (or wait for the webhook)
curl "https://api.pagr.eu/v1/render/jobs/<jobId>" \
  -H "Authorization: Bearer pagr_prod_xxxxxxxx"

Enqueue a job

Path parameters

Parameter	Type	Required	Description
templateId	string (UUID)	Yes	The template to render.
version	integer	Only for the specific-version form	The template version number to render.

Query parameters

Parameter	Type	Default	Description
persist	boolean	true	Whether the rendered documents are stored.
language	string	—	Language variant to render, for multilingual templates.

Request body

Field	Type	Default	Description
documents	array of objects	— (required)	One object per document. Same 50 MB / 32-level limits per document as a synchronous render; a test key caps the array at 10 entries.
callbackUrl	string	— (required)	A publicly reachable URL Pagr POSTs the webhooks to. Each POST is signed with your organisation’s webhook secret in an X-Pagr-Signature header — verify it before acting on the payload.
includeDocument	boolean	false	When true, each progress webhook carries its document’s PDF inline as Base64.

{
  "documents": [
    { "Title": "Acme Q3 Invoice", "Amount": 42 },
    { "Title": "Acme Q4 Invoice", "Amount": 58 }
  ],
  "callbackUrl": "https://your-app.example/pagr/callback?token=s3cr3t",
  "includeDocument": false
}

Payload limits are checked at enqueue time

Document size and nesting depth are validated before the job is accepted, so an accepted job never fails later on payload size. A rejected enqueue costs you nothing.

Response

202 Accepted:

{
  "jobId": "6b1c9f42-0d3e-4a58-b7c1-9e2f8a4d5c30",
  "requestedCount": 2,
  "state": "queued"       // always "queued" here — poll for progression
}

Field	Type	Description
jobId	string (UUID)	Use it to poll the job or correlate webhooks.
requestedCount	number	Documents submitted with the job.
state	string	Always queued on this response.

Poll a job

GET /v1/render/jobs/{jobId}

Parameter	Type	Required	Description
jobId	string (UUID), path	Yes	The job returned by the enqueue call.

Call it on an interval — every couple of seconds is fine — and stop once state is a terminal value. Response: 200:

{
  "jobId": "6b1c9f42-0d3e-4a58-b7c1-9e2f8a4d5c30",
  "state": "completed",            // lifecycle: pending | completed | failed
  "status": "partial",             // outcome:   ok | partial | failed | insufficient_credit (null while pending)
  "renderedCount": 1,
  "requestedCount": 2,
  "missingCount": 1,               // requestedCount − renderedCount
  "issues": [
    { "type": "MissingBinding", "severity": "Warning", "description": "…", "documentIndex": 1 }
  ],
  "startedAt": "2026-07-24T09:45:58Z",
  "completedAt": "2026-07-24T09:46:04Z",   // null while pending
  "failureReason": null                     // set only when state == "failed"
}

Response fields

Field	Type	Description
jobId	string (UUID)	The job.
state	string	The job lifecycle: pending (queued or rendering), completed (finished; documents were produced, including partial and credit-stopped runs), or failed (produced nothing).
status	string or null	The render outcome, same vocabulary as the sync envelope: ok, partial, failed, insufficient_credit. null while state is pending.
renderedCount	number	Documents produced so far.
requestedCount	number	Documents submitted.
missingCount	number	requestedCount − renderedCount.
issues	array	Per-document RenderIssue objects, each with its documentIndex.
startedAt	string (ISO 8601)	When the job started.
completedAt	string (ISO 8601) or null	When it reached a terminal state; null while pending.
failureReason	string or null	Human-readable reason, set only when state is failed.

state and status answer different questions

state is did the job finish running. status is how did the documents turn out. A job can be state: "completed" and status: "partial" at the same time — it ran to completion, but not every document rendered. Always read both.

Polling truncates the issue list; the webhook doesn’t

The two ways of collecting a job’s result do not return the same number of issues:

• The completion webhook carries every issue the job produced. It’s built in memory at the moment the job finishes, so nothing is dropped.
• Polling this endpoint returns at most 100. Only the first 100 issues are written to the database — a deliberate cap, so one pathological batch can’t bloat the row — and polling reads them back from there.

The counts are exact either way: renderedCount, requestedCount and missingCount are computed from the job, not from the issue list. So if you need the full diagnostic detail on a large batch, take it from the webhook payload; treat the polled issues array as a sample and trust the counts.

SDK reference

SDK	Enqueue	Poll once	Wait for terminal
Python	enqueue_batch_render(template_id, json_data_sets, callback_url, …)	get_job_status(job_id)	wait_for_job(job_id, poll_interval=2.0, timeout=None)
TypeScript	enqueueBatchRender(templateId, dataSets, callbackUrl, options?)	getJobStatus(jobId)	waitForJob(jobId, options?)
Java	enqueueBatchRender(templateId, dataSets, callbackUrl[, RenderOptions])	getJobStatus(jobId)	waitForJob(jobId[, pollInterval, timeout])
C#	EnqueueBatchRenderAsync(templateId, dataSets, callbackUrl, …)	GetJobStatusAsync(jobId)	WaitForJobAsync(jobId, pollInterval, timeout, …)
Ruby	enqueue_batch_render(template_id, json_data_sets, callback_url, …)	job_status(job_id)	wait_for_job(job_id, poll_interval:, timeout:)
C++	enqueue_batch_render(template_id, data_sets, callback_url, RenderOptions)	get_job_status(job_id)	wait_for_job(job_id, poll_interval, timeout)

Every SDK’s wait_for_job treats an unrecognised state as terminal (fail-open), so a state a newer server introduces can never trap the loop in an infinite wait.

wait_for_job gives up after 5 minutes by default

Leaving the timeout unset does not mean “wait forever” — every SDK applies a 5-minute overall deadline and then reports a timeout. A batch that legitimately runs longer needs either a bigger deadline or an explicit opt-out:

SDK	Default	Poll forever
Python	WAIT_FOR_JOB_DEFAULT_TIMEOUT = 300.0 s (also used for timeout=None)	timeout=math.inf
TypeScript	DEFAULT_WAIT_FOR_JOB_TIMEOUT_MS = 300_000	timeoutMs: Infinity
Java	DEFAULT_WAIT_TIMEOUT = Duration.ofMinutes(5) (also used for timeout == null)	waitForJobUnbounded(jobId[, pollInterval])
C#	PagrApiClient.DefaultWaitForJobTimeout = TimeSpan.FromMinutes(5) (also used for timeout: null)	timeout: Timeout.InfiniteTimeSpan
Ruby	DEFAULT_WAIT_FOR_JOB_TIMEOUT = 300 (also used for timeout: nil)	timeout: Float::INFINITY
C++	PagrApiClient::kDefaultWaitForJobTimeout (5 min)	PagrApiClient::kUnboundedWaitForJobTimeout

The deadline bounds the wait, not the job. A timed-out wait doesn’t cancel anything server-side — the render keeps going, and the webhook still fires. Java spells the opt-out as a separate method rather than a sentinel value, in keeping with the rest of its API.

Errors

Status	code	When
400	ValidationError	A test key submitted more than 10 documents, or an unknown language.
404	EntityNotFound	No job with this id exists for your organisation.
413	PayloadTooLarge	A document exceeds 50 MB.
503	QueueFull	The async render queue is at capacity — back off and retry.

See Errors for the full table.

Related articles

• Run renders in the background — the whole flow, step by step.
• Webhooks — the two callback payload shapes, the signature scheme, and how to secure your endpoint.
• Render a document — the synchronous form.
• Render Events — the in-app log of these jobs.