Get AI billing snapshot
The customer’s consumption state: mode, balance, kill switch and policy. balance carries the same three numbers in either mode with a denomination saying what they count, so a consumer that only wants “how much is left” never has to branch. credits is populated in credits mode with the pot, its upcoming expiries and a summary of the rate card; meters is populated in windows mode with one live entry per rolling allowance — used, remaining and the instant it resets, counting the open instance — which is the read to poll for a limits UI.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Customer to bill — the external id your application knows them by, or a Hyperline cus_… id. Resolved exactly the way AI telemetry resolves it.
1 - 255"acme-corp"
The agent making the call, as run({ agent }) names it. Optional, and absent means the customer's shared pool — which is what every call did before per-agent billing existed. Naming an agent only changes anything once an operator has given that agent a billing policy of its own; until then it resolves to the same shared pool and the response says so with agent: null.
1 - 128"invoice-copilot"
Response
Snapshot.
The billing scope that answered: the agent's own slug when it has a policy of its own, and null when the customer's shared pool answered — including when an agent was named but has no policy of its own.
"invoice-copilot"
The customer's billing mode, or null when no policy is configured.
wallet, credits, windows "wallet"
What the customer can spend. In wallet mode this is the shadow balance — micro-consumption never touches the wallet ledger directly. In credits mode it is the credit pot itself, read live. In windows mode the three numbers describe the binding window, the one with least room left and therefore the one that will refuse the next call; meters carries every window separately.
Whether the customer's kill switch is on. Consumption is still recorded when it is — blocking is a gate for check, not a way to lose ledger entries.
false
Null when no policy is configured.
The customer's rolling allowances, in windows mode — one entry per window the policy defines, in declaration order, counting the currently open instance. Null in every other mode. This is the live-meters read: poll it to render "37,500 of 50,000 left, resets at 14:14".
The customer's credit pot and rate card. Populated in credits mode, null in every other — including a credits-mode policy whose credit product the customer has no balance for, which check reports as credit_pot_missing.
What this scope does when it runs out, and where it stands right now. Null in wallet mode, which has no exhaustion boundary — its shadow balance already accrues past zero. mode: "refuse" is the default and is today's behaviour: the call that would cross the boundary is refused whole. mode: "metered" re-prices that whole call in USD instead and records it as overage.
The customer's agents that have a pool of their own, each with its own numbers. Never a total: two pools can be denominated in credits and in weighted allowance units, which have no common unit, so a summed figure across them would mean nothing. Empty when this snapshot was asked about one specific agent.