Returns every compute unit the caller's org has, from every source, each…
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…
GET /v1/visor/fleet
| Address | https://api.hanzo.ai/v1/visor/fleet |
| Method | GET |
| Operation | listFleet |
| Auth | Authorization: Bearer $HANZO_API_KEY |
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.
Request
GET /v1/visor/fleet takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | fleetBoard | ok |
200 body — 23 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
units | body | fleetUnit[] | — | Units is the union across sources — agent run-targets, BYO workers, BYO clusters and Visor machines — each row naming the source it came from. |
units[].host | body | string | — | Host is the unit's hostname. |
units[].kind | body | string | — | Kind is what the unit IS: laptop, cloud, gpu, cluster, machine or worker. |
units[].label | body | string | — | Label is the name to show a human — a target's label, a worker's hostname, a machine's display name. |
units[].metrics | body | fleetMetrics | — | |
units[].metrics.at | body | string | — | At is when this reading was MEASURED, RFC 3339 in UTC — not when the board was built. |
units[].metrics.gpuUtil | body | number | — | GPUUtil is aggregate accelerator utilization as a FRACTION of 1 — 0.42 is 42% busy, never 42. |
units[].metrics.load1 | body | number | — | Load1 is the host's 1-minute load average — runnable processes, not a percentage, so it is read against the unit's core count and can exceed 1. |
units[].metrics.memFree | body | integer | — | MemFree is host memory still available, in BYTES. |
units[].metrics.memUsed | body | integer | — | MemUsed is host memory in use, in BYTES. |
units[].queued | body | integer | — | Queued is how many renders are waiting on THIS GPU's own lane in the org's gpu-jobs queue. |
units[].running | body | integer | — | Running is what the unit is executing right now: agent sessions in flight for a run-target, claimed renders for a BYO GPU. |
units[].sessions | body | integer | — | Sessions is how many agent sessions are open on this unit. |
units[].source | body | string | — | Source is the plane this row came from: "agent" (a linked run-target), "byo" (a worker or cluster the org dialed in) or "visor" (a machine Hanzo provisioned). |
units[].spec | body | fleetSpec | — | |
units[].spec.arch | body | string | — | Arch is the CPU architecture, amd64 or arm64, and it is what decides whether a binary built for the fleet will run here. |
units[].spec.cpus | body | integer | — | CPUs is logical cores on the unit. |
units[].spec.gpuModel | body | string | — | GPUModel names the FIRST accelerator ("NVIDIA GB10") as the representative of the set; GPUs carries how many. |
units[].spec.gpus | body | integer | — | GPUs is how many accelerators the unit has. |
units[].spec.memory | body | integer | — | Memory is total system RAM in BYTES — not GB, and not what is free right now (fleetMetrics carries that). |
units[].spec.os | body | string | — | OS is the operating system the unit runs: linux, darwin or windows. |
units[].status | body | string | — | Status is liveness in the SOURCE's own vocabulary, because each plane decides it differently: a run-target's is derived from its heartbeat, a BYO worker's is… |
units[].unit | body | string | — | Unit is the SOURCE's own id for this unit — a run-target id, a BYO worker id, a Visor machine name — so a row links straight back to the face that owns it. |
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.listFleet();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()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.VisorAPI.ListFleet(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(&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).listFleet();curl https://api.hanzo.ai/v1/visor/fleet \
-H "Authorization: Bearer $HANZO_API_KEY"Tool visor, op listFleet — 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": "listFleet",
"input": {}
}
}
}'How is this guide?