/
Open Explorer

Concepts

Understand job states, completion, and download readiness

Accepted work only becomes useful when you know what state it is in, whether it can still move forward, and whether the finished output is actually ready to download. This page explains that lifecycle for both single renders and batches.

Single render

A single render job reports queued or processing until it reaches a terminal state: completed or failed.

Batch

Batch status and item status are separate signals, so overall completion does not mean every item succeeded.

Download readiness

Completion is required but not sufficient for download; the output must still exist and still be within retention.

Single Render Lifecycle

A single render job usually follows one short path

Single render follow up is built around one job ID. The status route tells you whether the job is still waiting, actively processing, or terminal. The file route is only relevant after status: "completed"and only while output is still available.

GET/v1/pdf/jobs/:id

GET/v1/pdf/jobs/:id/file

01

The job is accepted and usually starts queued

After the render is admitted, the job typically sits in a queued state while the platform moves it into processing.

02

The status route tells you whether to keep waiting

The status payload exposes timestamps, retry fields, error details, and outputAvailable. Retrieve artifacts through the explicit URL or file endpoint.

03

The job reaches a terminal status

For single render jobs, terminal means exactly completed or failed. Stop polling and either download while retained or handle the final error.

Single render lifecycle example
Accepted render
  -> status starts queued or processing
  -> retry fields may appear while the system requeues work
  -> terminal status becomes completed or failed

If completed
  -> outputAvailable is true only while retention is still active
  -> the file route can return the PDF

If failed
  -> error details explain why the job stopped
  -> the file route does not become downloadable

Batch Lifecycle

A batch tracks both the whole job and each item inside it

Batch follow up is broader than single render follow up. You need to understand the status of the batch as a whole and the state of each item that belongs to it. Treat them as separate signals.

GET/v1/pdf/batch/:id

GET/v1/pdf/batch/:id/zip

GET/v1/pdf/batch/:id/:itemId

01

The batch starts as one accepted job

The batch status route shows the overall batch status, lifecycle timestamps, progress counts, and when retained output expires.

02

Progress is reported at two levels

The progress block shows completed, failed, pending, throttled, and percentComplete counts, while each item reports its own state, output details, retryAttempt, and errors.

03

The batch job reaches a terminal status

Overall batch status can end as completed, failed, cancelled, or expired. A completed batch means processing is finished for the set, not that every item succeeded; inspect each item status before assuming file availability.

Batch lifecycle example
Accepted batch
  -> overall status begins queued or processing
  -> progress tracks completed, failed, pending, and throttled work
  -> items can finish at different times with different outcomes

When the batch reaches a terminal status
  -> overall status can be completed, failed, cancelled, or expired
  -> completed means no more processing, not universal item success
  -> item and zip downloads depend on retained completed outputs

Terminal States

Stop polling when the job can no longer make forward progress

Terminal state does not mean "everything succeeded." It means no additional processing will occur for that job record, so clients should stop polling and branch on final outcome.

How to think about terminal states

Completed

success terminal

Processing finished for that job record. For single render, completed is the only success terminal. For batch, completed means the batch workflow finished; it does not guarantee item level success for every entry.

Failed

failure terminal

The workflow ended in a non-success terminal state and will not make further progress without a new create request.

Cancelled or expired

batch terminal

Batch-only terminal statuses. cancelled means processing was explicitly stopped. expired means retained outputs are no longer available and batch status may be treated as not found.

Download Readiness

Completed does not help unless the output is still available

Download readiness is a stricter rule than lifecycle completion. A file route only works when the relevant output exists, belongs to the job or item you requested, and has not expired.

  • Single render download succeeds only when the job is completed and its stored output has not expired.
  • Batch item download succeeds only when that specific item is completed and still has retained output.
  • Batch zip download requires at least one retained completed output; expiration removes download availability.
  • A terminal success state can coexist with non-downloadable output after retention expiry.

Next Steps

Move from the lifecycle model into the route or failure page you need

Use the pages below when you are ready for exact response fields, route behavior, and failure handling.

Need single-job detail?

Open render jobs reference

Use the jobs page for exact single render status fields, retry signals, and file download behavior.

Jobs

Need batch status detail?

Open batch rendering reference

Use the batch page for progress payloads, item download behavior, zip retrieval, and batch-specific limits.

Batch

Need failure handling?

Open errors and limits

Use the errors page when you need shared retryability guidance, status meanings, and recovery decisions.

Errors