Shows one machine: its accounts, usage and live sessions.

GET /v1/link/devices/{machine}

Link → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/link/devices/{machine}`
Method	`GET`
Operation	`get_link_devices_by_machine`
Auth	`Authorization: Bearer $HANZO_API_KEY`

It answers one device — its host and OS labels, every account the caller has signed in on that machine with its latest usage, and how many agent sessions the caller currently has running on it. The device labels come from the most-recently-seen account, since a device is a projection of its links rather than a row of its own. A machine with none of the caller's accounts is 404, which is also the answer when the machine belongs to someone else — the scope makes the two indistinguishable, deliberately. The session count reports 0 where the agent plane is not mounted rather than failing the read.

Request

1 field.

Field	In	Type	Required	Description
`machine`	path	string	yes	Machine is the machine to act on, from the path.

Response

Status	Body	Meaning
`200`	deviceView	ok

200 body — 21 fields.

Field	In	Type	Always	Description
`accounts`	body	linkView[]	—	Accounts is every account the caller has signed in on this machine.
`accounts[].account`	body	string	—	Account is the provider-side account identifier, when the collector knows it.
`accounts[].billing`	body	string	—	Billing is how this account's inference bills — plan (the user's own subscription, metered here for visibility only) or commerce (the gateway path).
`accounts[].createdAt`	body	string	—	CreatedAt is when the link was first registered, RFC 3339 UTC.
`accounts[].host`	body	string	—	Host is the machine's human hostname label, from its most recent report.
`accounts[].id`	body	string	—	ID is the link's opaque handle ("link_" + 32 hex chars).
`accounts[].kind`	body	string	—	Kind is how the account authenticates: subscription or apikey.
`accounts[].lastSeen`	body	string	—	LastSeen is when the account last reported, RFC 3339 UTC.
`accounts[].machine`	body	string	—	Machine is the stable machine identifier the collector reports.
`accounts[].os`	body	string	—	OS is the machine's operating system label.
`accounts[].plan`	body	string	—	Plan is the provider plan label (e.g.
`accounts[].provider`	body	string	—	Provider is the AI provider this account belongs to (claude, openai, hanzo…).
`accounts[].status`	body	string	—	Status is linked or revoked.
`accounts[].updatedAt`	body	string	—	UpdatedAt is when the link was last refreshed, RFC 3339 UTC.
`accounts[].usage`	body	any	—	Usage is the last good usage snapshot, clamped and re-serialized to known fields at ingest.
`accounts[].user`	body	string	—	User is the owning subject — the validated caller who registered the link.
`activeSessions`	body	integer	—	ActiveSessions is how many agent sessions the caller currently has running on this machine; 0 where the agent plane is not mounted.
`host`	body	string	—	Host is the machine's hostname label, from its most-recently-seen account.
`lastSeen`	body	string	—	LastSeen is when any account on this machine last reported, RFC 3339 UTC.
`machine`	body	string	—	Machine is the stable machine identifier.
`os`	body	string	—	OS is the machine's operating system label.

Failure carries the platform error shape — see Errors.

Examples

hanzo links devices get <machine>

import { Configuration, LinkApi } from 'hanzoai';

const api = new LinkApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getLinkDevicesByMachine({ machine: 'machine' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import LinkApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = LinkApi(client).get_link_devices_by_machine(machine='machine')

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

resp, _, err := client.LinkAPI.GetLinkDevicesByMachine(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, link_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = link_api::get_link_devices_by_machine(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.LinkApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new LinkApi(client).getLinkDevicesByMachine();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were 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/link/devices/<machine> \
  -H "Authorization: Bearer $HANZO_API_KEY"

The door reaches link through the link tool, which names its 11 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_links"
         }
       }
     }'

Link API · All Hanzo APIs · Interactive reference

Shows one machine: its accounts, usage and live sessions.

Request

Response

Examples

On this page