# List summary URL: https://docs.hanzo.ai/docs/openapi/usage/get-usage-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 →](https://docs.hanzo.ai/docs/openapi/usage) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | --------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/usage/summary` | | **Method** | `GET` | | **Operation** | `get_usage_summary` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | 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. 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 \h or \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](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo usage summary ``` **SDK** **.ts** ```ts import { Configuration, UsageApi } from 'hanzoai'; const api = new UsageApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getUsageSummary(); ``` **.py** ```python 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() ``` **.go** ```go 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 } ``` **.rs** ```rust 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?; ``` **.java** ```java 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(); ``` **HTTP** ```bash curl https://api.hanzo.ai/v1/usage/summary \ -H "Authorization: Bearer $HANZO_API_KEY" ``` **MCP** Tool `usage`, op `get_usage_summary` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash 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](https://docs.hanzo.ai/docs/openapi/usage) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)