Shows plan consumption and Hanzo spend side by side.

GET /v1/link/usage/summary

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


Address	`https://api.hanzo.ai/v1/link/usage/summary`
Method	`GET`
Operation	`get_link_usage_summary`
Auth	`Authorization: Bearer $HANZO_API_KEY`

It answers the global usage board over one window: the caller's own linked accounts, metered from each provider's own login, alongside their org's Hanzo-routed inference. These come from different ledgers and mean different things, so every row is LABELLED by source, by scope and by availability, and THE TWO ARE NEVER SUMMED — a plan's percentage is not money, and a provider's own spend is not a Hanzo charge. The rows sit side by side and say what they are.

One resolver fixes the window for both halves, so the two sets always cover the same period. range is one of 1h, 24h, 7d or 30d and defaults to 24h; anything else is 400 rather than a silent substitution. A ledger that cannot answer reports available:false instead of a zero that would read as "no usage".

Request

1 field.

Field	In	Type	Required	Description
`range`	query	string	—	Range is the period, one of 1h, 24h, 7d or 30d; empty means 24h, and an unknown label is 400, never a silent substitution.

Response

Status	Body	Meaning
`200`	summaryResp	ok

200 body — 24 fields.

Field	In	Type	Always	Description
`account`	body	sourceState	—
`account.available`	body	boolean	—	Available reports whether this ledger answered; false is honest "unavailable", never a zero that would read as no usage.
`account.note`	body	string	—	Note says in prose what the ledger's numbers mean.
`account.scope`	body	string	—	Scope is whose usage the ledger measures: user or org.
`account.source`	body	string	—	Source is the table of record behind the ledger.
`from`	body	string	—	From is when the window opens, RFC 3339 UTC.
`hanzo`	body	sourceState	—
`hanzo.available`	body	boolean	—	Available reports whether this ledger answered; false is honest "unavailable", never a zero that would read as no usage.
`hanzo.note`	body	string	—	Note says in prose what the ledger's numbers mean.
`hanzo.scope`	body	string	—	Scope is whose usage the ledger measures: user or org.
`hanzo.source`	body	string	—	Source is the table of record behind the ledger.
`range`	body	string	—	Range is the resolved period label.
`rows`	body	totalView[]	—	Rows is the union of both ledgers, each row labelled by source and scope — concatenated, NEVER summed: a plan's percentage is not money.
`rows[].confidence`	body	string	—	Confidence says how real the row's numbers are.
`rows[].costCents`	body	integer	—	CostCents is the period's spend in cents, in the row's own ledger.
`rows[].provider`	body	string	—	Provider is the provider the row totals.
`rows[].requests`	body	integer	—	Requests is the period's request count.
`rows[].scope`	body	string	—	Scope is whose usage the row measures: user or org.
`rows[].source`	body	string	—	Source is whose meter the row came from: account or hanzo.
`rows[].tokens`	body	integer	—	Tokens is the period's total token count.
`rows[].usedPct`	body	number	—	UsedPct is the plan consumption percentage, on the account side.
`rows[].window`	body	string	—	Window is the window class the row totals, on the account side.
`rows[].windows`	body	integer	—	Windows is how many window instances the row folds.
`to`	body	string	—	To is where the window closes, EXCLUSIVE, RFC 3339 UTC — the instant the read was served.

Failure carries the platform error shape — see Errors.

Examples

hanzo links usage summary

import { Configuration, LinkApi } from 'hanzoai';

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

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

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

resp, _, err := client.LinkAPI.GetLinkUsageSummary(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_usage_summary(&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).getLinkUsageSummary();

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/usage/summary \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool link, op get_link_usage_summary — 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": "link",
         "arguments": {
           "op": "get_link_usage_summary",
           "input": {}
         }
       }
     }'

Link API · All Hanzo APIs · Interactive reference

Shows plan consumption and Hanzo spend side by side.

Request

Response

Examples

On this page