How jobs work

Processing is where work happens: every capability here is an asynchronous job that consumes credits and follows the contract on this page, regardless of type.

Processing jobs are asynchronous. You submit one, get a job back, and poll until it reaches a terminal state. Every job type shares the same lifecycle, the same status values and the same error format, so an integration that handles one handles all of them.

This page is the single home of that contract; per-type pages describe only what is specific to them.

Note on vocabulary: for historical reasons the v2 URLs say processes and the identifier is called processId. These are frozen and will not change. Everywhere else (documentation, schemas, new endpoints) the word is job.

Lifecycle

Status	Meaning
CREATED	The job was accepted and registered.
WAITING	The job is queued and waiting for a worker.
RUNNING	The job is being processed.
FINISHED	Terminal: the result is ready for download.
FAILED	Terminal: processing failed; see the error message.
CANCELLED	Terminal: the job was cancelled.

Tracking a job

• Poll: GET /v2/processes/{processId} returns the current status immediately; call it on an interval until the status is terminal.
• Longpoll: GET /v2/processes/longpoll/{processId} waits until the status changes, then returns. Repeat on 408 timeout.

Links

Every job response carries HATEOAS links. Use the rel field, not title, as the stable machine-readable identifier; titles are display text and may change. The longpoll link is present only while the job is non-terminal; its absence is the signal to stop polling.

Results

A finished job offers its result inline (in the content field of the status response), as a ZIP archive, and, where the job type produces page content, as PAGE XML. Results are retained for 24 hours after completion.

Errors

Errors are reported as JSON with statusCode, reasonPhrase and message. See Errors for the full taxonomy.