List 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.

GET /v1/compute/fleet

Compute → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/compute/fleet`
Method	`GET`
Operation	`listFleet`
Auth	`Authorization: Bearer $HANZO_API_KEY`

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/compute/fleet takes no parameters and no body — the credential is the whole request.

Response

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

200 body — 23 fields.

Field	In	Type	Always	Description
`units`	body	compute.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	compute.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 (double)	—	GPUUtil is aggregate accelerator utilization as a FRACTION of 1 — 0.42 is 42% busy, never 42.
`units[].metrics.load1`	body	number (double)	—	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 (int64)	—	MemFree is host memory still available, in BYTES.
`units[].metrics.memUsed`	body	integer (int64)	—	MemUsed is host memory in use, in BYTES.
`units[].queued`	body	integer (int64)	—	Queued is how many renders are waiting on THIS GPU's own lane in the org's gpu-jobs queue.
`units[].running`	body	integer (int64)	—	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 (int64)	—	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	compute.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 (int64)	—	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 (int64)	—	GPUs is how many accelerators the unit has.
`units[].spec.memory`	body	integer (int64)	—	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 online/offline on the 90s window, a BYO cluster's is "attached", and a Visor machine's is the provider's word for its lifecycle state.
`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

CLI

SDK

HTTP

MCP

hanzo compute fleet get

.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.listFleet();

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()

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

resp, _, err := client.ComputeAPI.ListFleet(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(&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).listFleet();

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

Tool compute, 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": "compute",
         "arguments": {
           "op": "listFleet",
           "input": {}
         }
       }
     }'

Compute API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList clusters — GET /v1/compute/clusters NextList jobs