Return the latest cached printer status

GET

/api/v1/printers/{printer_id}/status

const url = 'https://example.com/api/v1/printers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/status';
const options = {method: 'GET', headers: {'X-Label-Hub-Key': '<X-Label-Hub-Key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/api/v1/printers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/status \
  --header 'X-Label-Hub-Key: <X-Label-Hub-Key>'

Returns the most recent status written by the background probe worker (SNMP for tape printers, IPP for page printers; page printers add kind, printer_state, reasons, markers, trays and jobs_ahead). The response is served from printer_status_cache. When no probe has completed yet online is null and note explains why. Reads the hub’s cache only; never contacts the printer. Returns 404 when the printer is not registered.

Authorizations

APIKeyHeader

Parameters

Path Parameters

printer_id

required

Printer Id

string format: uuid

Responses

200

Successful Response

application/json

PrinterStatus

Printer status sourced from the printer_status_cache table.

The endpoint reads the cache row written by StatusProbeProducer instead of doing a synchronous SNMP probe inline. This makes the response fast (<10 ms) even when the printer is offline.

tape_loaded is a human-readable string such as "12mm laminated black/clear" or None when no tape is inserted. error_state mirrors the active PrinterError flags as a string, or None when the printer is ready. captured_at is the UTC timestamp of the probe that last updated the cache row. None means no probe has completed yet. For a page printer (kind="page") that went offline it stays the time of the last successful reading; online and last_error tell that it is stale. last_probe_age_s is the age of the cached reading in seconds (for an offline page printer: since its last successful reading). last_error is the exception message from the most recent failed probe. note carries a human-readable hint (e.g. “No probe yet”). polled is False when no status producer runs for the printer (SNMP discovery off, printer disabled or not wired). stale is True when the last probe attempt (printer_status_cache.updated_at) is older than max(90, 3 * probe interval, 2 * max backoff) seconds (an IPP printer that stopped answering is probed with a backoff of up to 300 s, so its bound is 600 s), or implausibly in the future. For an unpolled or stale printer online is None and the cached values (tape, error state, markers, trays) are not returned; captured_at and last_probe_age_s stay so a client can show how old the last reading is.

object

captured_at

Captured At

UTC timestamp of the probe that produced this reading; None if no probe yet. A page printer that went offline keeps the time of its last successful reading.

Any of:

string
null

string

error_state

Error State

Active error flags as a string; None when printer is ready

Any of:

string
null

string

identity_mismatch

Identity Mismatch

True while the device behind the printer’s address differs from the one the hub stored (a swapped printer). Sheet and calibration jobs are held meanwhile. Only the flag is returned here; the identity values are for admins.

boolean

jobs_ahead

Jobs Ahead

Jobs on the printer ahead of the hub’s own

Any of:

integer
null

integer

kind

Kind

‘page’ for IPP page printers; None for tape printers

Any of:

string
null

string

Allowed values: tape page

last_error

Last Error

Exception message from the most recent failed probe

Any of:

string
null

string

last_probe_age_s

Last Probe Age S

Age of the cached reading in seconds; for an offline page printer, since its last successful reading

Any of:

integer
null

integer

markers

Markers

Any of:

Array<object>
null

Array<object>

MarkerRead

One supply (toner, ink, waste container) of a page printer.

object

color

required

Color

Any of:

string
null

string

empty

required

Empty

boolean

level_percent

required

Level Percent

Any of:

integer
null

integer

low

required

Low

boolean

name

required

Name

string

some_remaining

required

Some Remaining

boolean

type

required

Type

Any of:

string
null

string

note

Note

Human-readable hint, e.g. ‘No probe yet’

Any of:

string
null

string

online

Online

True when the printer responded to the last SNMP probe; None = no probe yet

Any of:

boolean
null

boolean

polled

Polled

False when no status producer runs for this printer

boolean

default: true

printer_id

required

Printer Id

string format: uuid

printer_state

Printer State

Any of:

string
null

string

Allowed values: idle printing stopped

roll_prompt

Roll Prompt

True when the roll changed and the operator is still to be asked for the tape colour (PUT /printers/{id}/roll); False for an unpolled or stale printer

boolean

stale

Stale

True when the last probe attempt is older than the staleness bound

boolean

state_reasons

State Reasons

Any of:

Array<object>
null

Array<object>

ReasonRead

One printer-state-reasons keyword of a page printer (severity suffix removed).

object

blocking

required

Blocking

boolean

keyword

required

Keyword

string

severity

required

Severity

string

Allowed values: report warning error

tape_colour

Tape Colour

Tape colour from the operator’s roll record. The printer reports none over the network, so this stays None until a roll is recorded.

Any of:

string
null

string

Allowed values: white yellow green blue red black clear

tape_loaded

Tape Loaded

E.g. “12mm laminated black/clear”; None when no tape is loaded

Any of:

string
null

string

tape_width_mm

Tape Width Mm

Width of the loaded tape in mm; None when no tape is loaded or unknown

Any of:

integer
null

integer

trays

Trays

Any of:

Array<object>
null

Array<object>

TrayStatusRead

A configured tray of a page printer plus what the printer reports as loaded in it.

object

enabled

required

Enabled

boolean

is_default

required

Is Default

boolean

key

required

Key

string

label

required

Label

string

load_hint

required

Load Hint

Any of:

string
null

string

media

Media

Loaded media as the printer reports it; None when not reported

Any of:

string
null

string

Example

{
  "identity_mismatch": false,
  "kind": "tape",
  "polled": true,
  "printer_state": "idle",
  "roll_prompt": false,
  "stale": false,
  "state_reasons": [
    {
      "severity": "report"
    }
  ],
  "tape_colour": "white"
}

404

The printer is not registered.

application/json

DetailError

The error body the routes actually send: FastAPI’s {"detail": "<text>"}.

Routes raise HTTPException(status, detail="<text>"); this is the model that describes that body in OpenAPI. It is not :class:ProblemDetail, which no route sends.

object

detail

required

Detail

Human-readable explanation of the error

string

Example ^generated

{
  "detail": "example"
}

422

Validation Error

application/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

ctx

Context

object

input

Input

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example ^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}

Return the latest cached printer status

Authorizations

Parameters

Path Parameters

Responses

200

Example

404

Example generated

422

Example generated

Example ^generated

Example ^generated