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
| Address | https://api.hanzo.ai/v1/visor/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/visor/fleet/workers takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | workerList | ok |
200 body — 30 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
workers | body | 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… |
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 | — | 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 | 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 | 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… |
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 | — | 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
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, VisorApi } from 'hanzoai';
const api = new VisorApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.listFleetWorkers();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import VisorApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = VisorApi(client).list_fleet_workers()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.VisorAPI.ListFleetWorkers(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, visor_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = visor_api::list_fleet_workers(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.VisorApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new VisorApi(client).listFleetWorkers();curl https://api.hanzo.ai/v1/visor/fleet/workers \
-H "Authorization: Bearer $HANZO_API_KEY"Tool visor, 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": "visor",
"arguments": {
"op": "listFleetWorkers",
"input": {}
}
}
}'How is this guide?