List samples

The PER-PROVIDER view: one connected account's own consumption of its own plan — "my plan is 47% through its 6h window, resets at 14:20".

GET /v1/usage/samples

Usage → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/usage/samples`
Method	`GET`
Operation	`get_usage_samples`
Auth	`Authorization: Bearer $HANZO_API_KEY`

The PER-PROVIDER view: one connected account's own consumption of its own plan — "my plan is 47% through its 6h window, resets at 14:20".

current is the newest instance of each lane (the headline); windows is the history behind it. Both come from ONE deduped read, so they can never disagree. The rows are the caller's OWN linked accounts, scoped to the validated principal and its subject — never another user's, and never another org's.

Request

4 fields.

Field	In	Type	Required	Description
`account`	query	string	—	Account narrows to ONE linked account of that provider.
`provider`	query	string	—	Provider is the upstream to read, e.g. anthropic.
`range`	query	string	—	Range is the window to read: a count and a unit — 1h, 24h, 90d, any <N>h or <N>d — or day, week, month, all.
`window`	query	string	—	Window narrows to ONE window class: 6h, day, week or month.

Response

Status	Body	Meaning
`200`	usage.dashResp	ok
`default`	problem-details	refused

200 body — 48 fields.

Field	In	Type	Always	Description
`account`	body	string	—	Account is the linked account that was asked about, when one was named.
`available`	body	boolean	—	Available is false when the warehouse could not be read.
`current`	body	usage.usageWindowView[]	—	Current is the newest window instance of each lane — the dash headline.
`current[].account`	body	string	—	Account is the linked provider account the window belongs to.
`current[].cachedInputTokens`	body	integer (int64)	—	CachedInputTokens is the prompt tokens served from the provider's cache; omitted when unknown.
`current[].confidence`	body	string	—	Confidence says how much the counters beside it mean — a meter that reported only a percentage leaves them at zero, and this is how a reader tells that from a true zero.
`current[].costCents`	body	integer (int64)	—	CostCents is what the window cost on the PROVIDER's own plan, in US cents.
`current[].costLimitCents`	body	integer (int64)	—	CostLimitCents is the plan's spend ceiling for the window, in US cents.
`current[].currency`	body	string	—	Currency is the provider's currency when it is not US cents.
`current[].inputTokens`	body	integer (int64)	—	InputTokens is prompt tokens consumed in the window; omitted when unknown.
`current[].lane`	body	string	—	Lane is the meter lane this instance belongs to, e.g. a provider's own rolling-window meter.
`current[].machine`	body	string	—	Machine is the host whose meter reported the window.
`current[].outputTokens`	body	integer (int64)	—	OutputTokens is completion tokens produced in the window; omitted when unknown.
`current[].plan`	body	string	—	Plan is the subscription plan the account is on, as the provider names it.
`current[].requests`	body	integer (int64)	—	Requests is how many requests were made in the window; omitted when the meter did not report it.
`current[].resetsAt`	body	string	—	ResetsAt is when this window rolls over, RFC3339 UTC; omitted when unknown.
`current[].synthetic`	body	boolean	—	Synthetic marks an instance the meter inferred rather than read.
`current[].totalTokens`	body	integer (int64)	—	TotalTokens is the window's total tokens; omitted when unknown.
`current[].usedPct`	body	number (double)	—	UsedPct is how much of the window's allowance is consumed, 0–100.
`current[].window`	body	string	—	Window is the window class: 6h, day, week or month.
`current[].windowMinutes`	body	integer (int32)	—	WindowMinutes is the window's real length in minutes when the meter reported one; omitted when it did not.
`current[].windowStart`	body	string	—	WindowStart is when this window opened, RFC3339 UTC; omitted when unknown.
`from`	body	string	—	From is the inclusive start of that window, RFC3339 UTC.
`provider`	body	string	—	Provider is the upstream that was asked about, echoed back.
`range`	body	string	—	Range is the window that was served: 1h, 24h, 7d or 30d.
`scope`	body	string	—	Scope says whose rows these are: the caller's own linked accounts.
`source`	body	string	—	Source names the meter of record — the provider's own login, not Hanzo.
`to`	body	string	—	To is the exclusive end of that window, RFC3339 UTC.
`windows`	body	usage.usageWindowView[]	—	Windows is every instance in range, newest first — the history behind it.
`windows[].account`	body	string	—	Account is the linked provider account the window belongs to.
`windows[].cachedInputTokens`	body	integer (int64)	—	CachedInputTokens is the prompt tokens served from the provider's cache; omitted when unknown.
`windows[].confidence`	body	string	—	Confidence says how much the counters beside it mean — a meter that reported only a percentage leaves them at zero, and this is how a reader tells that from a true zero.
`windows[].costCents`	body	integer (int64)	—	CostCents is what the window cost on the PROVIDER's own plan, in US cents.
`windows[].costLimitCents`	body	integer (int64)	—	CostLimitCents is the plan's spend ceiling for the window, in US cents.
`windows[].currency`	body	string	—	Currency is the provider's currency when it is not US cents.
`windows[].inputTokens`	body	integer (int64)	—	InputTokens is prompt tokens consumed in the window; omitted when unknown.
`windows[].lane`	body	string	—	Lane is the meter lane this instance belongs to, e.g. a provider's own rolling-window meter.
`windows[].machine`	body	string	—	Machine is the host whose meter reported the window.
`windows[].outputTokens`	body	integer (int64)	—	OutputTokens is completion tokens produced in the window; omitted when unknown.
`windows[].plan`	body	string	—	Plan is the subscription plan the account is on, as the provider names it.
`windows[].requests`	body	integer (int64)	—	Requests is how many requests were made in the window; omitted when the meter did not report it.
`windows[].resetsAt`	body	string	—	ResetsAt is when this window rolls over, RFC3339 UTC; omitted when unknown.
`windows[].synthetic`	body	boolean	—	Synthetic marks an instance the meter inferred rather than read.
`windows[].totalTokens`	body	integer (int64)	—	TotalTokens is the window's total tokens; omitted when unknown.
`windows[].usedPct`	body	number (double)	—	UsedPct is how much of the window's allowance is consumed, 0–100.
`windows[].window`	body	string	—	Window is the window class: 6h, day, week or month.
`windows[].windowMinutes`	body	integer (int32)	—	WindowMinutes is the window's real length in minutes when the meter reported one; omitted when it did not.
`windows[].windowStart`	body	string	—	WindowStart is when this window opened, RFC3339 UTC; omitted when unknown.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo usage samples

.ts

.py

.go

.rs

.java

import { Configuration, UsageApi } from 'hanzoai';

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

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = UsageApi(client).get_usage_samples()

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

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

use hanzo_client::apis::{configuration::Configuration, usage_api};

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

let result = usage_api::get_usage_samples(&cfg, Default::default()).await?;

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

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new UsageApi(client).getUsageSamples();

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

MCP reaches usage through the usage tool, which names its 5 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_usage_analytics"
         }
       }
     }'

Usage API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList analytics NextList summary