List targets

Returns every machine registered to the caller's org, newest first, each with its live session load.

GET /v1/agent/targets

Agent → · All API references → · Get started →


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 — 49 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…
`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…
`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. 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 (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[].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

hanzo agent targets list

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

The method above is the one at the current release of the document. [email protected] (npm) was generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

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

MCP reaches agent through the agents tool, which names its 36 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_agent_conversations"
         }
       }
     }'

Agent API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page