API Reference
Track accepted render jobs and download finished files
This page is the source of truth for accepted single render follow up routes. Use it after create returns accepted work and you need the exact follow up contract: poll the job status route, interpret retry and dead letter indicators, and call the job file route only when download readiness is confirmed.
Auth model
Render auth
X-API-Key required
Accepted single render jobs stay on the machine authenticated rendering surface. These follow up routes do not use bearer identity.
Job ownership
scoped to the owning API key
Status and file retrieval only succeed for the API key that owns the job. A different key behaves like a missing job.
Follow-up surface
status first, file second
Accepted single render follow up is a two step flow: check status, then download from file route only when status shows completed output that is still available.
Status source
Use the job status route as the authoritative source for progress, retry signals, and terminal state.
Download rule
The file route only works after the job is completed and the output is still downloadable.
Retry visibility
Retry attempts, automatic requeue signals, and dead letter indicators are exposed directly on the status response.
Status → file flow
1) Start with statusUrl
GET /v1/pdf/jobs/:id
Poll until the job is terminal. Treat status as the source of truth for progress and retry state.
2) Confirm download readiness
completed + outputAvailable
Attempt retrieval only after status is completed and outputAvailable is true.
3) Call fileUrl
GET /v1/pdf/jobs/:id/file
Use the same API key that owns the job. If output is missing or expired, file returns 404.
Signed in dashboard users can follow the same accepted job lifecycle from dashboard render historyand per job detail pages without issuing manual API key follow up requests themselves.
Job Status Route
Poll one accepted job until it reaches a terminal state
Step 1 in accepted single render follow up: call status repeatedly until you see a terminal outcome. This route is the authoritative source for lifecycle state, retry progress, dead letter terminal failure, and download readiness signals.
GET/v1/pdf/jobs/:id
Request
Status polling uses the owning API key plus the accepted job identifier.
X-API-Key
required header
Use the same rendering key that owns the accepted job.
id
required path string
Accepted job identifier returned from the create response.
Response
Status returns the current job state, completion metadata, retry signals, and any terminal error details.
success
boolean
Signals that the job lookup succeeded for the current API key.
jobId
string
Stable identifier for the accepted render job.
status
queued, processing, completed, or failed
Current lifecycle state for the job.
inputMode
html, url, or template
Resolved input mode used when the job was created.
outputMode
binary, base64, or url
Resolved output mode requested at create time.
createdAt
ISO 8601 datetime
When the accepted job was first created.
updatedAt
ISO 8601 datetime
Latest status update for the job.
completedAt
ISO 8601 datetime or null
Set when the job reaches a terminal state.
outputAvailable
boolean
Whether retained output can be retrieved through the explicit URL or file endpoint.
downloadUrlEndpoint
relative path
Endpoint that issues a short-lived signed download URL.
fileName
string or null
Resolved file name for the finished PDF when available.
pdfSize
number
PDF size in bytes after completion, or 0 while the file is not ready.
pages
number
Page count for the finished PDF, or 0 while the file is not ready.
processingTimeMs
number
Observed processing time for the job, reported in milliseconds.
attemptCount
number
Current delivery attempt count for the queued render job.
retryAttempt
number or null
Current retry attempt when the job is queued for an automatic retry, otherwise null.
maxAttempts
number
Maximum delivery attempts configured for this queued workflow.
willRetry
boolean
True when the job will be retried automatically after a transient failure or capacity wait cycle.
deadLettered
boolean
True when the job exhausted retries and moved into a dead letter terminal failure state.
error
object or null
Present when the queue recorded a retry signal or terminal failure detail.
error.code
string
Machine-readable failure or retry code such as RETRY_SCHEDULED, CAPACITY_WAIT, or DEAD_LETTERED.
error.message
string
Human-readable explanation of the retry condition or terminal failure.
Status codes
200, 401, 404
200 returns the status payload. 401 means missing or invalid API key. 404 means the job does not exist for this key.
Job File Route
Download the finished PDF only after the job is ready
Step 2 in accepted single render follow up: call file only after status confirms readiness. This route is intentionally narrow and returns binary output only when completed output is still downloadable.
GET/v1/pdf/jobs/:id/file
Request
File retrieval uses the same API key and accepted job identifier as the status route.
X-API-Key
required header
Use the same rendering key that created and owns the accepted job.
id
required path string
Accepted job identifier returned from the original create response.
Response
A successful file response streams the finished PDF directly. It does not return JSON metadata.
200 binary
application/pdf
Returned when the accepted job is completed and the output is still downloadable for the current API key.
Content-Type
application/pdf
The response body is the finished PDF bytes.
Content-Disposition
attachment filename header
Uses the resolved file name so download clients receive a stable attachment name.
404 not downloadable
not found or not ready
Returned when the job is missing for the current key, still in progress, has no output, or the downloadable output has already expired.
401 unauthenticated
missing or invalid API key
Returned when render auth is absent or invalid for this request.
Job State Fields
Read state, completion, and output fields together
The status payload is most useful when you treat the state fields as a combined readiness signal instead of reading each field in isolation.
queued
accepted but not finished
The job has been admitted and is waiting for worker capacity or retry reprocessing. Output is not ready yet.
processing
actively rendering
A worker is currently generating the PDF. Keep polling the status route instead of attempting file download.
completed
terminal success
The job finished successfully. completedAt is set, and outputAvailable, fileName, pdfSize, and pages describe the finished file.
failed
terminal failure
The job stopped without a finished PDF. Read error.code, error.message, willRetry, and deadLettered to understand whether the failure is final.
completedAt + outputAvailable
download readiness pair
A completed timestamp alone is not enough. Check terminal completion plus outputAvailable.
pdfSize + pages
finished file metadata
These fields describe the finished PDF after successful completion. They stay at zero while the file is not yet available.
Retry Fields
Use retry signals to separate in-progress recovery from terminal failure
The status response exposes whether the queue will retry the job automatically, whether capacity wait is in progress, and whether the job has exhausted all retry attempts.
retryAttempt
number or null
Set when the job is currently on a retry cycle. Null means no retry attempt is active right now.
maxAttempts
number
Upper bound for delivery attempts on this queue-backed workflow.
willRetry
boolean
True when the current failure state is recoverable and the queue intends to try again automatically.
deadLettered
boolean
True when the job exhausted retries and has entered a final dead letter failure state.
RETRY_SCHEDULED
queued retry signal
The renderer hit a transient failure and has already scheduled another attempt. Expect status queued plus willRetry true.
CAPACITY_WAIT
queued capacity signal
The workflow is waiting for capacity before retrying or resuming execution. Treat it as in-progress work, not terminal failure.
DEAD_LETTERED
terminal retry exhaustion
The queue stopped retrying. This is a final failed state and the client should not keep polling for success.
Download Readiness
Check status first, then download only when the file is still available
Keep the follow up flow strict to avoid avoidable 404 responses: status is the readiness gate, and file is the final retrieval call.
Ready to download
completed with available output
Download after the job is completed and outputAvailable is true. Use downloadUrlEndpoint for URL handoff or the file route for direct bytes.
Still queued or processing
keep polling status
Do not call the file route while work is still queued, retrying, or actively processing. The file is not ready yet.
Completed but expired
file route can return 404
A completed job does not guarantee indefinite file availability. Once output expires, the file route behaves like any other not-downloadable job.
Wrong key or missing job
404 scope protection
Jobs are scoped to the owning API key. A different key behaves the same as a missing job and does not leak ownership details.
Open the shared errors page for 404, auth, and retryability guidance.
Next Steps
Move from job polling into lifecycle guidance, errors, or the accepted-work guide
Use these canonical pages when you need lifecycle concepts, shared failure guidance, or the full accepted render sequence that starts at create and ends at file retrieval.
Need the mental model?
Open jobs and lifecycle
Use the concept page for state transitions, terminal outcomes, retry states, and download readiness across render workflows.
Need failure guidance?
Open shared errors reference
Use the errors page for retryability rules, status code expectations, and shared error shape guidance.
Need the end-to-end workflow?
Open accepted render flow guide
Use the guide for create, polling, retry handling, and final download in one continuous integration sequence.