Get a print job status
Read one CloudPrint print job until it reaches the terminal printed or failed status.
What this endpoint does
Read one CloudPrint print job until it reaches the terminal printed or failed status.
Authentication
Send a short-lived access token in Authorization: Bearer <access_token>.
Required scopes: print_jobs:read
Request
Production base URL: https://public-api.cloudprint.me/api/v1/print-jobs/{printJobId}
Parameters
| Name | Location | Type | Required | Description | Constraints |
|---|---|---|---|---|---|
printJobId | path | string (uuid) | yes | — | — |
Request body
This endpoint has no request body.
Example requests
cURL
bash
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/55555555-5555-4555-8555-555555555555 \
-H "Authorization: Bearer $ACCESS_TOKEN"Response
HTTP status: 200 — Print job
Response fields
| Name | Type | Required | Description | Constraints |
|---|---|---|---|---|
print_job_id | string (uuid) | yes | Stable UUID of the print job; persist it for status checks and support. | — |
document_id | string (uuid) | yes | Stable UUID returned after a successful document upload. | — |
document_mime_type | string | yes | MIME type of the supplied document. | example: "application/pdf" |
document_format | string | yes | Explicit print format, such as pdf or raw. | enum: pdf, raw; example: "pdf" |
document_raw_language | string | null | yes | Printer command language used by RAW data, for example ZPL or EPL. | enum: tspl, zpl, cpcl, escpos; example: null |
printer_id | string (uuid) | yes | Stable CloudPrint UUID of the destination printer. | — |
status | string | yes | Current resource or workflow state; use the endpoint-specific enum values. | enum: pending, reserved, printing, printed, failed, cancelled; example: "pending" |
copies | integer | yes | Number of copies CloudPrint asks the printer to produce. | min: 1; max: 99; example: 1 |
intent | string | yes | Business purpose of the print job, used for diagnostics and sensible defaults. | enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label" |
color_mode | string | yes | Requested color handling; default leaves the decision to the printer configuration. | enum: default, monochrome, color; example: "default" |
duplex_mode | string | yes | Requested one-sided or two-sided printing mode. | enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default" |
media_width_mm | number | null | yes | Requested media or label width in millimetres. | min: 1; max: 2000; example: 58 |
media_height_mm | number | null | yes | Requested media or label height in millimetres. | min: 1; max: 2000; example: 40 |
dpi | integer | null | yes | Target print resolution in dots per inch; use a value supported by the printer. | min: 72; max: 2400; example: 203 |
scale_mode | string | yes | Controls whether the document keeps its size or is fitted to the target media. | enum: none, fit; example: "none" |
orientation | string | yes | Requested page orientation; default uses printer settings. | enum: default, portrait, landscape; example: "default" |
offset_x_mm | number | yes | Horizontal print offset in millimetres. | min: -2000; max: 2000; example: 0 |
offset_y_mm | number | yes | Vertical print offset in millimetres. | min: -2000; max: 2000; example: 0 |
margin_top_mm | number | yes | Additional print margin in millimetres. | min: 0; max: 2000; example: 0 |
margin_right_mm | number | yes | Additional print margin in millimetres. | min: 0; max: 2000; example: 0 |
margin_bottom_mm | number | yes | Additional print margin in millimetres. | min: 0; max: 2000; example: 0 |
margin_left_mm | number | yes | Additional print margin in millimetres. | min: 0; max: 2000; example: 0 |
created_at | string (date-time) | yes | ISO 8601 timestamp recorded by CloudPrint. | — |
reserved_at | string | null (date-time) | yes | ISO 8601 timestamp recorded by CloudPrint. | — |
started_at | string | null (date-time) | yes | ISO 8601 timestamp recorded by CloudPrint. | — |
completed_at | string | null (date-time) | yes | ISO 8601 timestamp recorded by CloudPrint. | — |
failure_reason | string | null | yes | Machine-readable or diagnostic reason recorded when printing fails. | — |
Example response
json
{
"print_job_id": "11111111-1111-4111-8111-111111111111",
"document_id": "11111111-1111-4111-8111-111111111111",
"document_mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"printer_id": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"copies": 1,
"intent": "shipping_label",
"color_mode": "default",
"duplex_mode": "default",
"media_width_mm": 58,
"media_height_mm": 40,
"dpi": 203,
"scale_mode": "none",
"orientation": "default",
"offset_x_mm": 0,
"offset_y_mm": 0,
"margin_top_mm": 0,
"margin_right_mm": 0,
"margin_bottom_mm": 0,
"margin_left_mm": 0,
"created_at": "2026-08-06T12:00:00Z",
"reserved_at": null,
"started_at": null,
"completed_at": null,
"failure_reason": null
}Errors
| HTTP status | Description |
|---|---|
401 | OAuth bearer token is missing or invalid |
403 | OAuth bearer token does not include print_jobs:read |
404 | Print job not found |
422 | Print job ID is invalid |
429 | Rate limit exceeded |
500 | Unexpected error |
Integration guidance
- Poll with a bounded interval and stop at the terminal
printedorfailedstatus. - Persist
failure_reason,print_job_idandX-Request-Idfor operator support. - Do not create a replacement job merely because one polling request timed out.
Related documentation
Create a print jobSend an uploaded CloudPrint document to a selected printer with idempotency and explicit print options.List print jobsList recent CloudPrint print jobs with cursor pagination for operational screens and support tools.Troubleshoot agents, printers and print jobsDiagnose CloudPrint integration problems by request ID, job status, agent connectivity, printer capabilities and API error code.