List summary

Answers GET /v1/usage/summary: the caller's own usage footprint over one window — the categorized spend roll-up from the commerce ledger, the org's LLM usage totals from the warehouse, and the caller's OWN linked provider accounts beside the org's Hanzo-routed usage.

GET /v1/usage/summary

Usage → · All API references → · Get started →

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

Every source degrades INDEPENDENTLY to honest zeros and says so in sources and in its own available flag, so a partial deploy reports "no data" rather than fabricating spend. The account rows and the Hanzo rows are concatenated and never summed: a plan's percent is not money.

The response is org-scoped from the validated principal and marked no-store — a signed-out caller is refused.

Request

3 fields.

Field	In	Type	Required	Description
`range`	query	string	—	Range is the window: a count and a unit — 24h, 7d, 90d, any <N>h or <N>d — or day, week, month, all, custom.
`start`	query	string	—	Start is the inclusive window start, RFC3339.
`end`	query	string	—	End is the exclusive window end, RFC3339.

Response

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

200 body — 56 fields.

Field	In	Type	Always	Description
`accounts`	body	usage.Accounts	—
`accounts.account`	body	usage.SourceState	—
`accounts.account.available`	body	boolean	—	Available is whether this side's ledger answered.
`accounts.account.note`	body	string	—	Note is the human sentence that says what this side's numbers mean, so a board cannot present a plan percentage as a Hanzo charge.
`accounts.account.scope`	body	string	—	Scope is whose rows this side carries: "user" or "org".
`accounts.account.source`	body	string	—	Source is the table of record the rows came from.
`accounts.hanzo`	body	usage.SourceState	—
`accounts.hanzo.available`	body	boolean	—	Available is whether this side's ledger answered.
`accounts.hanzo.note`	body	string	—	Note is the human sentence that says what this side's numbers mean, so a board cannot present a plan percentage as a Hanzo charge.
`accounts.hanzo.scope`	body	string	—	Scope is whose rows this side carries: "user" or "org".
`accounts.hanzo.source`	body	string	—	Source is the table of record the rows came from.
`accounts.rows`	body	usage.TotalView[]	—	Rows is the two row sets CONCATENATED, never summed — each row says which side it came from.
`accounts.rows[].confidence`	body	string	—	Confidence says how much the counters mean; a percentage-only meter leaves them at zero.
`accounts.rows[].costCents`	body	integer (int64)	—	CostCents is the row's cost in US cents.
`accounts.rows[].provider`	body	string	—	Provider is the upstream the usage was measured against.
`accounts.rows[].requests`	body	integer (int64)	—	Requests is how many requests the row covers.
`accounts.rows[].scope`	body	string	—	Scope is whose row it is: "user" for the caller's own linked accounts, "org" for the whole tenant's Hanzo-routed usage.
`accounts.rows[].source`	body	string	—	Source is where the row came from: "account" is the provider's own meter on the caller's linked account, "hanzo" is Hanzo-routed inference.
`accounts.rows[].tokens`	body	integer (int64)	—	Tokens is the total tokens the row covers.
`accounts.rows[].usedPct`	body	number (double)	—	UsedPct is how much of a plan window the row consumed, 0–100.
`accounts.rows[].window`	body	string	—	Window is the meter window class the row rolls up, when it has one.
`accounts.rows[].windows`	body	integer (int64)	—	Windows is how many window instances rolled up into the row.
`end`	body	string	—	End is the window's exclusive end, RFC3339 UTC.
`interval`	body	string	—	Interval is the bucket width the spend series is gap-filled at.
`llm`	body	usage.LLM	—
`llm.available`	body	boolean	—	Available is false when the warehouse was not connected or a query blipped.
`llm.completionTokens`	body	integer (int64)	—	CompletionTokens is the output half.
`llm.costCents`	body	integer (int64)	—	CostCents is what they cost the org, in US cents.
`llm.models`	body	integer (int64)	—	Models is how many distinct models were used.
`llm.promptTokens`	body	integer (int64)	—	PromptTokens is the input half of that total.
`llm.requests`	body	integer (int64)	—	Requests is how many completions the org made in the window.
`llm.source`	body	string	—	Source names the warehouse table the totals came from.
`llm.tokens`	body	integer (int64)	—	Tokens is the total tokens those completions consumed.
`range`	body	string	—	Range is the window label that was served.
`scope`	body	usage.usageScope	—
`scope.org`	body	string	—	Org is the IAM org slug the rows were read under — the validated principal's, never a client header.
`scope.user`	body	string	—	User is the caller's own subject, whose linked-account rows the accounts block carries.
`sources`	body	usage.Sources	—
`sources.commerce`	body	boolean	—	Commerce is whether the billing ledger answered the spend block.
`sources.warehouse`	body	boolean	—	Warehouse is whether the usage warehouse answered the LLM block.
`spend`	body	usage.Spend	—
`spend.available`	body	boolean	—	Available is false when the commerce ledger was unconfigured or unreachable.
`spend.availableCents`	body	integer (int64)	—	AvailableCents is what of that balance is still spendable.
`spend.balanceCents`	body	integer (int64)	—	BalanceCents is the prepaid wallet's balance, in US cents.
`spend.byCategory`	body	usage.CategorySpend[]	—	ByCategory is the window's spend split by ledger category, largest first.
`spend.byCategory[].category`	body	string	—	Category is the bucket the ledger's own tag mapped to.
`spend.byCategory[].cents`	body	integer (int64)	—	Cents is what the org spent in that bucket over the window, in US cents.
`spend.byCategory[].count`	body	integer (int64)	—	Count is how many ledger lines rolled up into it.
`spend.mtdCents`	body	integer (int64)	—	MTDCents is commerce's authoritative month-to-date consumed figure, which is a different period from the window and is not derived from it.
`spend.overageCents`	body	integer (int64)	—	OverageCents is month-to-date consumption beyond the plan's allowance.
`spend.series`	body	usage.SpendPoint[]	—	Series is the window's spend over time, gap-filled at the window's interval.
`spend.series[].cents`	body	integer (int64)	—	Cents is the consumption recorded in that bucket, in US cents.
`spend.series[].t`	body	string	—	T is the bucket's start instant, RFC3339 UTC.
`spend.source`	body	string	—	Source names where the roll-up came from.
`spend.totalCents`	body	integer (int64)	—	TotalCents is consumption over the requested window, in US cents.
`start`	body	string	—	Start is the window's inclusive start, RFC3339 UTC.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo usage summary

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

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

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

resp, _, err := client.UsageAPI.GetUsageSummary(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_summary(&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).getUsageSummary();

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

Tool usage, op get_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": "usage",
         "arguments": {
           "op": "get_usage_summary",
           "input": {}
         }
       }
     }'

Usage API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList samples NextCreate usage