Skip to navigation

Retrieve a job

View as Markdown

A job with its status: queued, delivered to the printer, printed, failed, expired or cancelled. Jobs are kept for 7 days after they end.

Scope: jobs:read.

Authentication

AuthorizationBearer

A restricted API key, tc_rk_live_ and 32 characters. Send it as Authorization: Bearer <key>. A key lists its scopes, and each operation below names the one it needs; a key may also be limited to one customer. An owner or a developer of the organization makes a key in the dashboard, under API keys, after a code sent to their e-mail. The key is shown once, when it is made. An owner or a developer can revoke it there, and a revoked key stops working within a minute.

Path parameters

jobstringRequired
The job's id.

Response

The job.
client_reference_idstring or null

The id of this job in your own system, such as an order number, or null. Not unique: the same value can be on many jobs, and GET /v1/jobs?client_reference_id= lists every job that carries it (the last 7 days). No personal data.

completed_atstring or null
created_atstring
customerstring
delivered_atstring or null
expires_atstring
When the job stops being offered to the printer.
idstring
kindstring

api (yours), welcome (the first-connection receipt) or test (a test print: never billed).

locationstring
metadatamap from strings to strings or null
objectstring
printerstring
profilestring or null

The profile the document was rendered for: the id of a preset (x-tillcast-profiles lists them). A plain string and not an enum, so that a profile that is retired never breaks a client. null for a job that was queued as ready printer data and not rendered from a document, such as every job from before documents were rendered.

reasonstring or null
Why the job did not print.
result_codestring or null
The printer's own status code for the job.
size_byteslong>=0

The size in bytes of what the printer is sent: the rendered document, after the transport step. Not the size of the document you sent.

statusstring

queued, delivered, printed, failed, expired or cancelled.

transportstring or null

The transport step applied to the rendered bytes: its id and revision, such as cloudprnt-star.1. A later correction of a step changes new jobs only, and this tells which jobs were rendered with which. null where profile is.

warningslist of objects

What the renderer noticed in the document, in the order it happened: at most 21 (the first 20, and a too_many_warnings that says there were more). Always there, an empty list for a document with nothing to say. Kept with the job: a replay of the request and every later read return the same list.

Errors

401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error