Hanzo
OpenapiVisor

Returns the caller org's BYO machines — the ones that dialed in via `hanzo…

Returns the caller org's BYO machines — the ones that dialed in via `hanzo link` — with everything each host reported about itself.

GET /v1/visor/fleet/workers

Addresshttps://api.hanzo.ai/v1/visor/fleet/workers
MethodGET
OperationlistFleetWorkers
AuthAuthorization: Bearer $HANZO_API_KEY

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.

Request

GET /v1/visor/fleet/workers takes no parameters and no body — the credential is the whole request.

Response

StatusBodyMeaning
200workerListok

200 body — 30 fields.

FieldInTypeAlwaysDescription
workersbodybyoWorker[]Workers is one row per connected BYO machine, each carrying the host's own report (GPUs, driver versions, capabilities) rather than a normalized view.
workers[].archbodystringArch/CPUs/Memory are the connecting host's static CPU spec, mirrored from the registration: Arch is runtime.GOARCH (amd64 | arm64), Memory is total RAM in…
workers[].capabilitiesbodystring[]Capabilities is what this worker offers the org: "studio.render" when the node can render, "engine.serve" when it serves a model endpoint.
workers[].cpuModelbodystringCPUModel is the processor as the host names it ("Apple M3 Max"), for display.
workers[].cpusbodyintegerCPUs is the host's logical core count.
workers[].cudabodystringCuda is the host's CUDA toolkit version.
workers[].driverbodystringDriver is the host's NVIDIA kernel driver version — distinct from Cuda, and the one that bounds which CUDA versions can run on this box.
workers[].enginebodyengineAdvertisement
workers[].engine.apisbodystring[]APIs are the wire formats the engine serves on that one port: "openai", "anthropic", or both.
workers[].engine.modelsbodystring[]Models are the model ids the node's own GET /v1/models answered with — what this GPU can actually be asked for.
workers[].engine.statusbodystringStatus is "ready" when the node's engine answered, "unreachable" when it did not.
workers[].engine.urlbodystringURL is the base address the node advertised its engine on — where a model call to this GPU is sent.
workers[].firstSeenbodystringFirstSeen is when this node first dialed in, RFC 3339 — the start of its presence record, which hanzo unlink ends.
workers[].gpusbodybyoGPU[]GPUs are the accelerators the host found on itself.
workers[].gpus[].archbodystringArch is the card's native compile target ("gfx1151"), which is what a kernel has to be built for.
workers[].gpus[].memoryTotalbodystringMemoryTotal is the card's VRAM in the units the host reported it in ("122880 MiB") — a display string, not a byte count.
workers[].gpus[].namebodystringName is the card's model exactly as its own tooling named it ("NVIDIA GB10"), never normalized — an operator matches what they see here against what nvidia-smi…
workers[].gpus[].unifiedbodybooleanUnified reports that CPU and GPU share one memory pool (an APU or SoC), so MemoryTotal is not private to the GPU and the host competes for it.
workers[].hipbodystringHip is the host's HIP runtime version, the AMD counterpart to Cuda.
workers[].hostnamebodystringHostname is what the host calls itself.
workers[].idbodystringID is the node's id in the fleet — the sanitized hostname it registered under, which is also the unit its samples and its gpu-jobs lane key on.
workers[].jobQueuebodystringJobQueue is the tasks NAMESPACE this worker claims render jobs out of — "gpu-jobs" unless hanzo link was pointed at another.
workers[].lastHeartbeatbodystringLastHeartbeat is the most recent beat this node sent, RFC 3339.
workers[].locationbodystringLocation is always "on-prem" — a machine that dialed in has no cloud region, and inventing one would put it somewhere it is not.
workers[].memorybodyintegerMemory is the host's total RAM in BYTES.
workers[].osbodystringOs is the host's operating system: linux, darwin or windows.
workers[].providerbodystringProvider is always "byo": this machine is the operator's, not one Hanzo provisioned.
workers[].rocmbodystringRocm is the host's ROCm version.
workers[].statusbodystringStatus is "online" when the last heartbeat landed within 90s, else "offline" — so it is a fact about heartbeat freshness, not about the box being powered on.
workers[].versionbodystringVersion is the hanzo CLI version running on the node.

Failure carries the platform error shape — see Errors.

Examples

hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.


Visor API · All Hanzo APIs · Interactive reference

How is this guide?

On this page