List targets
Returns every machine registered to the caller's org, newest first, each with its live session load.
GET /v1/agent/targets
| Address | https://api.hanzo.ai/v1/agent/targets |
| Method | GET |
| Operation | get_agent_targets |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Returns every machine registered to the caller's org, newest first, each with its live session load.
Request
GET /v1/agent/targets takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | agent.targetList | ok |
default | problem-details | refused |
200 body — 50 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
targets | body | agent.targetView[] | — | Targets is every target registered to the caller's org. |
targets[].capacity | body | string | — | Capacity is a human summary of what the machine has ("8 vCPU / 32G", "1× GB10"), up to 256 characters. |
targets[].createdAt | body | string | — | CreatedAt is when the machine was first registered, RFC 3339 in UTC. |
targets[].host | body | string | — | Host is the hostname sessions on this machine report, and it is a JOIN KEY, not a label: a session naming this host counts against the load below even when it names no target id, and a re-link of the same (org, host, owner) refreshes this row instead of creating a second. |
targets[].id | body | string | — | ID is the machine's handle, minted as "tgt_" + 32 hex characters. |
targets[].kind | body | string | — | Kind is what sort of destination this is, from a closed five: laptop | cloud | gpu | cluster | machine. |
targets[].label | body | string | — | Label is the name a person gave the machine ("workshop"), up to 128 characters. |
targets[].metrics | body | agent.Metrics | — | |
targets[].metrics.at | body | integer (int64) | — | unix seconds, server-stamped |
targets[].metrics.cpuTemp | body | number (double) | — | CPUTemp is the CPU package temperature in °C. |
targets[].metrics.cpuUtil | body | number (double) | — | CPUUtil is the busy fraction of all cores over the sample window, 0..1. |
targets[].metrics.decode | body | number (double) | — | Decode is generation throughput over the sample window, in tokens per second. |
targets[].metrics.diskRead | body | number (double) | — | DiskRead is the block-device read rate in bytes per second. |
targets[].metrics.diskTotal | body | integer (int64) | — | DiskTotal is the size of those filesystems, in bytes. |
targets[].metrics.diskUsed | body | integer (int64) | — | DiskUsed is the space used across local block filesystems, in bytes. |
targets[].metrics.diskWrite | body | number (double) | — | DiskWrite is the block-device write rate in bytes per second. |
targets[].metrics.gpuMemTotal | body | integer (int64) | — | GPUMemTotal is dedicated VRAM in bytes; absent when the GPU shares system memory (unified). |
targets[].metrics.gpuMemUsed | body | integer (int64) | — | GPUMemUsed is the memory held by GPU processes, in bytes. |
targets[].metrics.gpuPower | body | number (double) | — | GPUPower is the total GPU power draw in watts. |
targets[].metrics.gpuPowerLimit | body | number (double) | — | GPUPowerLimit is the total enforced GPU power limit in watts; absent when the driver reports none. |
targets[].metrics.gpuTemp | body | number (double) | — | GPUTemp is the hottest GPU's temperature in °C. |
targets[].metrics.gpuUtil | body | number (double) | — | 0..1 aggregate utilization |
targets[].metrics.kvCache | body | number (double) | — | KVCache is the KV-cache occupancy, 0..1. |
targets[].metrics.load1 | body | number (double) | — | Load1 is the machine's own one-minute load average — a count of runnable and uninterruptible tasks, NOT a percentage and NOT already divided by core count, so it is read against Spec.CPUs: 8.0 is idle on 16 cores and swamped on 4. |
targets[].metrics.load5 | body | number (double) | — | Load5 is the same figure averaged over five minutes. |
targets[].metrics.load15 | body | number (double) | — | Load15 is the same figure over fifteen. |
targets[].metrics.memFree | body | integer (int64) | — | bytes |
targets[].metrics.memUsed | body | integer (int64) | — | bytes |
targets[].metrics.model | body | string | — | Model is the model id(s) served on this machine, comma-separated, at most 128 bytes. |
targets[].metrics.netRx | body | number (double) | — | NetRx is the receive rate of physical interfaces in bytes per second. |
targets[].metrics.netTx | body | number (double) | — | NetTx is the transmit rate of physical interfaces in bytes per second. |
targets[].metrics.prefill | body | number (double) | — | Prefill is prompt (prefill) throughput over the sample window, in tokens per second. |
targets[].metrics.running | body | integer (int64) | — | Running is the number of requests being served now. |
targets[].metrics.ttft | body | number (double) | — | TTFT is the mean time to first token, in seconds, of requests that started in the window. |
targets[].metrics.waiting | body | integer (int64) | — | Waiting is the number of requests queued. |
targets[].metricsAt | body | string | — | MetricsAt is when that heartbeat was recorded, RFC 3339 in UTC, and the SERVER stamps it — a client cannot backdate or forge the staleness clock. |
targets[].running | body | integer (int64) | — | Running is how many of those are in running right now — the number a dispatcher weighs against Capacity. |
targets[].serving | body | boolean | — | Serving says whether a run the caller sends here now would be taken: the machine is the caller's (or the caller is an org admin), and it is online with a runner that polled for work within the last 90 seconds — the online and runner half is what dispatch checks (TargetDispatchable). |
targets[].sessions | body | integer (int64) | — | Sessions is how many of the org's sessions are mapped to this machine, by target id OR by matching Host. |
targets[].spec | body | agent.Spec | — | |
targets[].spec.arch | body | string | — | amd64 | arm64 | ... |
targets[].spec.cpus | body | integer (int64) | — | logical cores |
targets[].spec.gpus | body | agent.GPU[] | — | GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write. |
targets[].spec.gpus[].memory | body | integer (int64) | — | VRAM bytes, 0 = unknown |
targets[].spec.gpus[].model | body | string | — | "GB10", "8060S", "RTX 4090" |
targets[].spec.gpus[].vendor | body | string | — | nvidia | amd | apple | intel | ... |
targets[].spec.memory | body | integer (int64) | — | total RAM, bytes |
targets[].spec.os | body | string | — | linux | darwin | windows |
targets[].status | body | string | — | Status is the EFFECTIVE liveness — online | offline | draining — not the stored one. |
targets[].updatedAt | body | string | — | UpdatedAt is the last write to the row, same format — which for a beating machine is its last heartbeat, since a heartbeat IS a write. |
Failure carries the platform error shape — see Errors.
Examples
CLI
SDK
HTTP
MCP
hanzo agent targets list.ts
.py
.go
.rs
.java
import { Configuration, AgentApi } from 'hanzoai';
const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgentTargets();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentApi(client).get_agent_targets()cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)
resp, _, err := client.AgentAPI.GetAgentTargets(context.Background()).Execute()
if err != nil {
return err
}use hanzo_client::apis::{configuration::Configuration, agent_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = agent_api::get_agent_targets(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentApi;
ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));
var result = new AgentApi(client).getAgentTargets();curl https://api.hanzo.ai/v1/agent/targets \
-H "Authorization: Bearer $HANZO_API_KEY"MCP reaches agent through the agent tool, which names its 38 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "list_agents"
}
}
}'Was this page useful?