Fleet
Fleet — 6 operations on https://api.hanzo.ai.
The REST reference for Fleet — 6 operations, generated from the OpenAPI document.
| Base URL | https://api.hanzo.ai |
| Operations | 6 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
fleet
Cancels a queued or running render in the caller's org.
POST /v1/fleet/jobs/{id}/cancel
Cancels a queued or running render in the caller's org. The engine cancel is org-scoped, so a tenant can only ever cancel its OWN job: a job in another tenant's shard is 404, exactly like one that never existed. An already-finished job is 409.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the job (activity) id, from the URL path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
id | string | — | ID is the job (activity) id, from the URL path. |
reason | string | — | Reason is recorded on the cancellation; empty records "canceled from console". |
run | string | — | Run is the run id; empty defaults to the job id, which is what the dispatcher sets (runId == activityId == prompt_id), s |
Returns the caller org's gpu-jobs render queue, each row tagged with the GPU it targets (empty = the shared any-GPU lane) and the node claiming it, optionally narrowed to one GPU's queue and/or one status.
GET /v1/fleet/jobs
Returns the caller org's gpu-jobs render queue, each row tagged with the GPU it targets (empty = the shared any-GPU lane) and the node claiming it, optionally narrowed to one GPU's queue and/or one status.
A job whose worker died — STARTED with an elapsed lease and not yet reclaimed — reads "stalled", not "running". Fail-soft: an unavailable tasks engine yields an empty queue rather than an error.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
gpu | query | string | — | GPU selects one node's lane: jobs TARGETED at it (gpu:<node>) or CLAIMED by it. |
status | query | string | — | Status selects one lifecycle state: queued, running, stalled, completed, failed or canceled. |
Returns the caller org's utilization series, oldest first.
GET /v1/fleet/samples
Returns the caller org's utilization series, oldest first.
A rejected narrower is a 400 carrying its own reason (the vocabulary is ours and safe to echo); a warehouse failure is logged and answered 503 "unavailable", because a chart that silently reads "no load" when the truth is "we cannot tell" is worse than one that says so. An ABSENT warehouse is different again: it returns an empty series, which renders honestly as "no samples yet".
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
unit | query | string | — | Unit selects one compute unit's series by its source-local id. |
source | query | string | — | Source selects one plane: "agent", "byo" or "visor". |
range | query | string | — | Range is the lookback window (e.g. |
Records a BYO worker's live GPU utilization into the SAME series the fleet board overlays.
POST /v1/fleet/samples
Records a BYO worker's live GPU utilization into the SAME series the fleet board overlays. The org is the validated principal and source/kind are fixed server-side, so a worker names only its own metrics — never another tenant or another source. Answers 202: the warehouse write is DETACHED (its own bounded context, never in the response path), so a slow or absent warehouse cannot stall a heartbeat.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
gpuModel | string | — | |
gpuUtil | number | — | GPUUtil is accelerator utilization as a fraction 0..1; the warehouse clamps anything outside that. |
gpus | integer | — | GPUs is how many accelerators the reading covers, GPUModel the representative model name. |
host | string | — | Host is the node's hostname, for display. |
memFree | integer | — | |
memUsed | integer | — | MemUsed and MemFree are host memory in bytes. |
unit | string | — | Unit is the reporting node's own id — the same id it registered under, and the key the board joins this series onto. |
Returns the caller org's BYO machines — the ones that dialed in via hanzo link — with everything each host reported about itself.
GET /v1/fleet/workers
Returns the caller org's BYO machines — the ones that dialed in
via hanzo link — with everything each host reported about itself. The Machines
and GPUs pages fold the same data into their normalized shapes; this is the
canonical raw list a fleet view (or the CLI's status) reads.
Returns every compute unit the caller's org has, from every source, each carrying its latest utilization: agent run-targets, the BYO machines that dialed in, attached BYO clusters and Visor-provisioned machines.
GET /v1/fleet
Returns every compute unit the caller's org has, from every source, each carrying its latest utilization: agent run-targets, the BYO machines that dialed in, attached BYO clusters and Visor-provisioned machines.
A unit with a live snapshot of its own keeps it; the rest are overlaid from the utilization series, and only when the sample agrees about the SOURCE — two planes could mint the same unit id, and a board must never show one machine's load on another's row. BYO GPU units also carry their gpu-jobs queue depth. Every source is folded in independently: a broken one costs its own rows and nothing else.
How is this guide?