Jobs & polling

Creating a job#

Send an Idempotency-Key with every create. Within 24 hours, a retry with the same key returns the job it already created instead of starting a second one, so a timeout on your side never runs or charges a job twice. The answer is 202 with the Job, usually queued.

Lifecycle#

• progress (0–100) and stage move while the job runs. Repairs report the engine's stages; inspect and tool jobs report a coarser progress.
• attempt counts how often a worker took the job. If a worker is lost the job is queued again (up to three attempts) and the lost attempt is never charged.
• analysis (inspect) and result (repair, tool) appear once the job has succeeded and its outputs passed verification.
• usage (live jobs): held_credits while it runs, then charged_credits and charge_basis. Credits & billing

Repair stages, in order:

import transform preprocess smooth extract_decals close_holes remove_degenerate clearance thickness volume smoothing non_manifold construct reduce texture_projection clean hollow cuber export analyze

Polling#

Poll the job every two seconds or so until it reaches succeeded, failed or cancelled. Inspect jobs usually take seconds to minutes, repairs minutes; the hard limits per attempt are 3600 s for inspect, 7200 s for repair and 1800 s for a tool. An Exact Check's checker gets 290 s at most and is stopped by 300 s. Give up waiting on your side if you must, but the job keeps running: poll it again later. Exact Check jobs can call a webhook instead.

curl -sS "$API/v1/jobs/$JOB_ID" -H "Authorization: Bearer $PRINTY3D_API_KEY" \
  | jq '{status, stage, progress, queue, error_code, error_detail}'

GET /v1/jobs lists the jobs of your account and key mode, cursor-paginated (limit, cursor), when you track many at once.

Events#

Every change of status, stage or progress is a durable, ordered event {sequence, status, stage, progress, created_at}. Pass after (0 the first time, then the page's next_after) to get only the events you have not seen. Use events to draw a progress bar or a timeline; use the job itself to decide when it is done.

Queue and capacity#

Live jobs run on a fleet of rented GPUs. While a live job is queued, its queue field tells you where it stands (refreshed every 30 seconds):

When no GPU can start a live job, POST /v1/jobs answers 503 capacity_exhausted with Retry-After and a reason; nothing is queued or held. A live job that is already queued fails free, with error_code: capacity_exhausted, after 10 minutes without capacity or 24 hours in the queue.

Exact Check jobs run on their own CPU workers, not on the GPU fleet, so GPU capacity never refuses them and their queue.capacity is null. When no Exact Check worker is running, a live check gets 503 capacity_exhausted with reason: "cad_unavailable" instead, and a queued one fails free after 10 minutes without a worker.

Cancelling#

A queued job is cancelled at once; a running one is stopped and its outputs are never published. Cancelling a cancelled job is harmless; a succeeded or failed job answers 409 job_not_cancellable. A job cancelled before it started is free; one cancelled while running is charged the time it ran.

When a job fails#

error_detail carries the worker's own explanation, for example the last lines of the engine's output. It helps when you report a problem; do not parse it.