---
title: "PATCH /v1/print-jobs/{id}/status"
method: PATCH
path: "/v1/print-jobs/{id}/status"
---

# PATCH /v1/print-jobs/{id}/status

`PATCH /v1/print-jobs/{id}/status`

## Path parameters

- `id` string, required

## Request body

- object
  - `status` 'QUEUED' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'ERROR' | 'RETRYING' | 'PAUSED' | 'CANCELLED', required
  - `organizationId` string — Organization ID (optional, defaults to user's primary organization)
  - `reason` string — Reason for the status change (required when setting to CANCELLED or FAILED)
  - `force_download` boolean — When re-queuing, set force_download on print_options
  - `force` boolean — Force-cancel: skip printer stop command and write DB directly (escape hatch for Pulse outages)
  - `error_code` string — Machine-readable error code to persist on the job (used when transitioning to error/failed/cancelled)
  - `error_message` string — Human-readable error description to persist on the job for end-user visibility
  - `retry_handoff_expires_at` string, date-time — Exact retry handoff lease, or explicit null for an unleased claim
  - `release_printer_ready` boolean — Atomically mark the claimed printer ready while re-queuing, fenced by this job's lock ownership
  - `claim_generation` string, uuid — Immutable generation returned by the claim being released
  - `expected_printer_id` string, uuid — Printer owned by the claim being released

## Response `200`

Default Response

- object
  - `success` boolean
  - `forced` boolean

## Other responses

- `400` — Default Response
- `401` — Default Response
- `404` — Default Response
- `409` — Default Response
- `500` — Default Response
- `504` — Default Response

---

[API](https://skmtc.net/printhiv3d/apis/hive-api-documentation.md) · [All operations](https://skmtc.net/printhiv3d/apis/hive-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/printhiv3d/hive-api-documentation/versions/3b06bcb5f808/schema)