post_v1_usage

Ingests a batch of account-usage samples — what a developer's OWN AI accounts have consumed of their OWN plans, metered from each provider's own login — and appends them to the warehouse series.

Ingests a batch of account-usage samples — what a developer's OWN AI accounts have consumed of their OWN plans, metered from each provider's own login — and appends them to the warehouse series. Answers 202.

Send either a samples array or one sample's fields at the top level. Every sample needs a provider, a machine and a known window class; an unknown window or kind is refused rather than silently rewritten, because a dash filled with a class nobody reported is worse than an error. There is no timestamp field: the server owns the observation clock, and a sample says which window it measured with windowStart or resetsAt.

It is FAIL-SOFT on storage: a warehouse outage costs a poll of history (stored:false), never a failed request. It records usage ONLY — the link registry is refreshed separately via POST /v1/links, so there is one and only one way to update an account row.


Tool	`post_v1_usage`
Door	`https://api.hanzo.ai/v1/mcp`
Method	`tools/call` (JSON-RPC 2.0)
Arguments	22
Operation	`POST /v1/usage`
Product	usage

Arguments

Field	Type	Required	Default	Description
`account`	`string`	—	—	Account is the linked account the window was metered from.
`cachedInputTokens`	`integer`	—	—	CachedInputTokens is the prompt tokens the provider served from cache.
`confidence`	`string`	—	—	Confidence says how much the counters below mean.
`costCents`	`integer`	—	—	CostCents is what the window cost on the PROVIDER's own plan, in US cents.
`costLimitCents`	`integer`	—	—	CostLimitCents is the plan's spend ceiling for the window, in US cents.
`currency`	`string`	—	—	Currency is the provider's currency when it is not US cents.
`inputTokens`	`integer`	—	—	InputTokens is prompt tokens consumed in the window.
`kind`	`string`	—	—	Kind is subscription or apikey. Empty is accepted; anything else is refused.
`lane`	`string`	—	—	Lane is the meter lane within the account.
`machine`	`string`	—	—	Machine is the host whose meter read the window. Required on every sample.
`outputTokens`	`integer`	—	—	OutputTokens is completion tokens produced in the window.
`plan`	`string`	—	—	Plan is the provider plan the account is on, e.g. a Claude Max plan.
`provider`	`string`	—	—	Provider is the upstream the account belongs to, e.g. anthropic. Required on every sample.
`requests`	`integer`	—	—	Requests is how many requests the window covers.
`resetsAt`	`string`	—	—	ResetsAt is when the measured window rolls over, RFC3339.
`samples`	`sampleReq[]`	—	—	Samples is the batch form: every lane a poller measured, in one call. When it is non-empty the top-level sample fields are ignored.
`synthetic`	`boolean`	—	—	Synthetic marks a window the meter inferred rather than read.
`totalTokens`	`integer`	—	—	TotalTokens is the window's total tokens.
`usedPct`	`number`	—	—	UsedPct is how much of the window's allowance is consumed, 0–100.
`window`	`string`	—	—	Window is the window class: 6h, day, week or month. Required, and a class this surface does not know is refused rather than rewritten.
`windowMinutes`	`integer`	—	—	WindowMinutes is the window's real length in minutes, as the meter reports it.
`windowStart`	`string`	—	—	WindowStart is when the measured window opened, RFC3339. This is how a backfill states WHICH window it measured; the server always owns the observation clock, so there is no timestamp field.

This tool's schema does not declare which fields are required, nor any default, nor any enumerated value set. The columns above are empty because the door publishes nothing there, not because the answer is "none" — where a field is constrained, the constraint is stated in that field's own description.

Object types

sampleReq are objects this tool's fields refer to. Each is declared inside the tool's own schema.

sampleReq

Field	Type	Required	Default	Description
`account`	`string`	—	—	Account is the linked account the window was metered from.
`cachedInputTokens`	`integer`	—	—	CachedInputTokens is the prompt tokens the provider served from cache.
`confidence`	`string`	—	—	Confidence says how much the counters below mean.
`costCents`	`integer`	—	—	CostCents is what the window cost on the PROVIDER's own plan, in US cents.
`costLimitCents`	`integer`	—	—	CostLimitCents is the plan's spend ceiling for the window, in US cents.
`currency`	`string`	—	—	Currency is the provider's currency when it is not US cents.
`inputTokens`	`integer`	—	—	InputTokens is prompt tokens consumed in the window.
`kind`	`string`	—	—	Kind is subscription or apikey. Empty is accepted; anything else is refused.
`lane`	`string`	—	—	Lane is the meter lane within the account.
`machine`	`string`	—	—	Machine is the host whose meter read the window. Required.
`outputTokens`	`integer`	—	—	OutputTokens is completion tokens produced in the window.
`plan`	`string`	—	—	Plan is the provider plan the account is on, e.g. a Claude Max plan.
`provider`	`string`	—	—	Provider is the upstream the account belongs to, e.g. anthropic. Required.
`requests`	`integer`	—	—	Requests is how many requests the window covers.
`resetsAt`	`string`	—	—	ResetsAt is when the measured window rolls over, RFC3339. Empty is allowed; anything else that is not RFC3339 is refused.
`synthetic`	`boolean`	—	—	Synthetic marks a window the meter inferred rather than read.
`totalTokens`	`integer`	—	—	TotalTokens is the window's total tokens.
`usedPct`	`number`	—	—	UsedPct is how much of the window's allowance is consumed, 0–100.
`window`	`string`	—	—	Window is the window class: 6h, day, week or month. Required, and a class this surface does not know is refused rather than rewritten.
`windowMinutes`	`integer`	—	—	WindowMinutes is the window's real length in minutes, as the meter reports it.
`windowStart`	`string`	—	—	WindowStart is when the measured window opened, RFC3339. Empty is allowed; anything else that is not RFC3339 is refused.

Call it

A tools/call carries every argument in one flat object — nothing binds to a path or a query string. Every declared argument is shown, because the door marks none of them required.

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": "post_v1_usage",
         "arguments": {
           "account": "<account>",
           "cachedInputTokens": 0,
           "confidence": "<confidence>",
           "costCents": 0,
           "costLimitCents": 0,
           "currency": "<currency>",
           "inputTokens": 0,
           "kind": "<kind>",
           "lane": "<lane>",
           "machine": "<machine>",
           "outputTokens": 0,
           "plan": "<plan>",
           "provider": "<provider>",
           "requests": 0,
           "resetsAt": "<resetsAt>",
           "samples": [
             {}
           ],
           "synthetic": false,
           "totalTokens": 0,
           "usedPct": 0,
           "window": "<window>",
           "windowMinutes": 0,
           "windowStart": "<windowStart>"
         }
       }
     }'

Values are placeholders derived from each field's declared type. tools/list needs no credential; tools/call does — called without one the door answers HTTP 200 with a JSON-RPC result whose isError is set and whose text says what was missing. How to get a key →

The operation behind it

Operation	Route	Product	Summary
`cloud_post_v1_usage`	`POST /v1/usage`	usage	Ingests a batch of account-usage samples — what a developer's OWN AI accounts have consume

The same capability over plain HTTP is in the usage API reference, on https://api.hanzo.ai.

All 834 tools · The door · API reference

Generated from tools/list on https://api.hanzo.ai/v1/mcp — 834 tools captured 2026-08-01 (this build read the vendored copy; the door was unreachable).

Arguments

Object types

sampleReq

Call it

The operation behind it

On this page