Every admitted call produces a usage record the moment it is admitted — before any provider I/O. That record is what you are billed on, what your limits count against, and what you use to answer "why did this cost that?"
How a call is charged#
Charging is reserve → settle → release, in integer micro-USD (1 USD = 1,000,000 micro-USD):
- Reserve. Admission computes a conservative estimate — a ceiling over the input plus the
requested output limit (1024 tokens if you do not set
max_tokens) — and holds it against the project wallet. Every call holds at least one micro-USD, so even a price that rounds to zero needs a funded wallet. - Settle. The provider's verified usage replaces the estimate with the actual charge. Token-priced products meter input and output tokens separately at the published per-million-token rates; per-request products charge their flat price.
- Release. Whatever was reserved above the actual charge returns to the wallet's available balance.
You are billed on actual usage, not on the estimate. The reservation exists to stop a call that was never going to be affordable, not to price it.
When the outcome is uncertain#
A call that fails is not automatically free, and never retried at your expense:
- Definite failure — a known pre-dispatch error or a definite provider 4xx — releases the reservation in full. Charged: zero.
- Uncertain outcome — a timeout, an incomplete or 5xx response, a stream that ends without usage — keeps the reservation open as Reconciling. No automatic paid retry happens.
Uncertain calls land in a reconciliation queue operated by platform administrators: a human reviews the upstream evidence, records a reason, and either charges a verified amount (never more than the hold) or releases it. A reservation abandoned for five minutes becomes eligible; a completed call can never be settled or reconciled twice. Your usage views show these calls as held until they resolve — the money is neither spent nor available.
The invocation id#
Every admitted response carries X-AIGrid-Invocation, set before the provider is called. It is
the id of the usage record, and streamed error frames repeat it — so a reply that fails, is
truncated or is cut off still hands you the thread to follow.
Keep it. A failed reply is not evidence of an unbilled one: if your client disconnects mid-stream, the server keeps draining the provider and settles the charge. When a charge needs explaining, the invocation id is the first thing to look up and the first thing support will ask for.
Reading your usage#
/api/v2/tenants/{tenantID}/usage/api/v2/tenants/{tenantID}/consumption/{callID}/api/v2/tenants/{tenantID}/projects/{projectID}/budget| View | Shows |
|---|---|
| Usage list | one row per call: time, project, user or key prefix, product, modality, whether it streamed, status, tokens, latency, and the reserved and charged micro-USD |
| Request detail | one call: reservedMicro, chargedMicro, releasedMicro, whether it is held or settled, the provider outcome, a safe explanation, and the invocation's audit events |
| Project budget | fundedMicro, chargedMicro, reservedMicro, availableMicro — what the wallet holds, owes, and can still spend |
A call still waiting on its reservation shows the hold, not a charge it has not incurred.
Who can see what#
| View | Who |
|---|---|
| Organization usage | organization Owner · Administrator |
| Own calls | every member |
| Request detail | the caller, or an Owner/Administrator — anyone else gets 404 |
The organization view is oversight, not spending authority: reading every row does not grant the right to make calls or fund wallets.
Next#
- Caps and spend controls — bounding spend before it happens
- Errors — every code a caller can see, and what clears it