OpenapiAgents
Returns every machine registered to the caller's org, newest first, each with…
Returns every machine registered to the caller's org, newest first, each with its live session load.
GET /v1/agents/targets
| Address | https://api.hanzo.ai/v1/agents/targets |
| Method | GET |
| Operation | get_agents_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/agents/targets takes no parameters and no body — the credential is the whole request.
Response
| Status | Body | Meaning |
|---|---|---|
200 | targetList | ok |
200 body — 29 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
targets | body | 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… |
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 | Metrics | — | |
targets[].metrics.at | body | integer | — | unix seconds, server-stamped |
targets[].metrics.gpuUtil | body | number | — | 0..1 aggregate utilization |
targets[].metrics.load1 | body | number | — | 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… |
targets[].metrics.load5 | body | number | — | Load5 is the same figure averaged over five minutes. |
targets[].metrics.load15 | body | number | — | Load15 is the same figure over fifteen. The three together are what separate a machine that is busy right now from one that has been busy all along — which is… |
targets[].metrics.memFree | body | integer | — | bytes |
targets[].metrics.memUsed | body | integer | — | bytes |
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 | — | Running is how many of those are in running right now — the number a dispatcher weighs against Capacity. |
targets[].sessions | body | integer | — | Sessions is how many of the org's sessions are mapped to this machine, by target id OR by matching Host. |
targets[].spec | body | Spec | — | |
targets[].spec.arch | body | string | — | amd64 | arm64 | ... |
targets[].spec.cpus | body | integer | — | logical cores |
targets[].spec.gpus | body | GPU[] | — | GPUs is every accelerator the machine advertises, one entry each, capped at 32 on write. |
targets[].spec.gpus[].memory | body | integer | — | 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 | — | 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
hanzo agents targets listimport { Configuration, AgentsApi } from 'hanzoai';
const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgentsTargets();from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentsApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentsApi(client).get_agents_targets()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.AgentsAPI.GetAgentsTargets(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, agents_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = agents_api::get_agents_targets(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentsApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new AgentsApi(client).getAgentsTargets();curl https://api.hanzo.ai/v1/agents/targets \
-H "Authorization: Bearer $HANZO_API_KEY"The door reaches agents through the agents tool, which names its 36 operations with its own verbs — this one among them, under a name only the door 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_agent_conversations"
}
}
}'How is this guide?