List workers

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

GET /v1/compute/fleet/workers

Compute → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/compute/fleet/workers`
Method	`GET`
Operation	`listFleetWorkers`
Auth	`Authorization: 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/compute/fleet/workers takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	compute.workerList	ok
`default`	problem-details	refused

200 body — 30 fields.

Field	In	Type	Always	Description
`workers`	body	compute.byoWorker[]	—	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[].arch`	body	string	—	Arch/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 BYTES — the same fields a code-linked run-target carries, so the /v1/compute/fleet board renders a linked node's arch + cores + RAM like any other unit.
`workers[].capabilities`	body	string[]	—	Capabilities is what this worker offers the org: "studio.render" when the node can render, "engine.serve" when it serves a model endpoint.
`workers[].cpuModel`	body	string	—	CPUModel is the processor as the host names it ("Apple M3 Max"), for display.
`workers[].cpus`	body	integer (int64)	—	CPUs is the host's logical core count.
`workers[].cuda`	body	string	—	Cuda is the host's CUDA toolkit version.
`workers[].driver`	body	string	—	Driver 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[].engine`	body	compute.engineAdvertisement	—
`workers[].engine.apis`	body	string[]	—	APIs are the wire formats the engine serves on that one port: "openai", "anthropic", or both.
`workers[].engine.models`	body	string[]	—	Models are the model ids the node's own GET /v1/models answered with — what this GPU can actually be asked for.
`workers[].engine.status`	body	string	—	Status is "ready" when the node's engine answered, "unreachable" when it did not.
`workers[].engine.url`	body	string	—	URL is the base address the node advertised its engine on — where a model call to this GPU is sent.
`workers[].firstSeen`	body	string	—	FirstSeen is when this node first dialed in, RFC 3339 — the start of its presence record, which `hanzo unlink` ends.
`workers[].gpus`	body	compute.byoGPU[]	—	GPUs are the accelerators the host found on itself.
`workers[].gpus[].arch`	body	string	—	Arch is the card's native compile target ("gfx1151"), which is what a kernel has to be built for.
`workers[].gpus[].memoryTotal`	body	string	—	MemoryTotal is the card's VRAM in the units the host reported it in ("122880 MiB") — a display string, not a byte count.
`workers[].gpus[].name`	body	string	—	Name 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 tells them on the box.
`workers[].gpus[].unified`	body	boolean	—	Unified 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[].hip`	body	string	—	Hip is the host's HIP runtime version, the AMD counterpart to Cuda.
`workers[].hostname`	body	string	—	Hostname is what the host calls itself.
`workers[].id`	body	string	—	ID 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[].jobQueue`	body	string	—	JobQueue is the tasks NAMESPACE this worker claims render jobs out of — "gpu-jobs" unless `hanzo link` was pointed at another.
`workers[].lastHeartbeat`	body	string	—	LastHeartbeat is the most recent beat this node sent, RFC 3339.
`workers[].location`	body	string	—	Location is always "on-prem" — a machine that dialed in has no cloud region, and inventing one would put it somewhere it is not.
`workers[].memory`	body	integer (int64)	—	Memory is the host's total RAM in BYTES.
`workers[].os`	body	string	—	Os is the host's operating system: linux, darwin or windows.
`workers[].provider`	body	string	—	Provider is always "byo": this machine is the operator's, not one Hanzo provisioned.
`workers[].rocm`	body	string	—	Rocm is the host's ROCm version.
`workers[].status`	body	string	—	Status 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[].version`	body	string	—	Version is the `hanzo` CLI version running on the node.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo compute fleet workers

.ts

.py

.go

.rs

.java

import { Configuration, ComputeApi } from 'hanzoai';

const api = new ComputeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.listFleetWorkers();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ComputeApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ComputeApi(client).list_fleet_workers()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.ComputeAPI.ListFleetWorkers(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, compute_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = compute_api::list_fleet_workers(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ComputeApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ComputeApi(client).listFleetWorkers();

curl https://api.hanzo.ai/v1/compute/fleet/workers \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool compute, op listFleetWorkers — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "compute",
         "arguments": {
           "op": "listFleetWorkers",
           "input": {}
         }
       }
     }'

Compute API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList samples NextList alerts