Billing
IQ shows input, output, cached and thinking tokens when the provider reports them. Thinking tokens normally use the output rate and are charged once. You can inspect token usage and cost in Requests. This page covers cache costs, thinking budgets, team budgets and billing errors.
Token classes
- Input tokens are the prompt tokens billed by the provider.
- Output tokens are the model's response tokens.
- Cached tokens are input tokens the destination provider served out of its own prompt cache. They are billed, at the provider's discounted cache-read rate, not at zero. See below.
- Thinking tokens are reasoning tokens reported by the provider. They normally use the model's output rate. IQ shows their cost separately when the provider reports them.
What "cached" costs
Two different things produce a cached number on your bill, and they bill in opposite ways, so it is worth being precise about which one you are looking at.
A gateway response-cache hit is billed at zero. When IQ serves a request out of its own response cache it never calls the provider at all, so there is no upstream cost to pass through. It still counts against your rate limits and against your daily budget, because both checks run before the cache lookup happens. A hit skips the provider round trip entirely, so it costs nothing and returns faster than the original request did.
A provider prompt-cache read is a different animal. The request did go upstream, the provider recognised a prefix it had already stored, and it charged you its discounted cache-read rate for those tokens. That rate is substantially below the uncached input rate, but it is not free. The other half of that trade is the write side: seeding a provider prompt cache costs more per token than an uncached input token would have, so a prefix that is written often and read rarely loses money. The dashboard now reports the read and write sides separately on each request's detail page, so whether your prompt-cache strategy pays for itself is something you can inspect rather than infer. How much a cache read saves depends on the provider's cache-read rate and on how much of the prompt was served from cache; each request's detail page shows the actual split.
For the mechanics of the gateway's own response cache, including the exact and semantic layers, conversation-scoped caching for agent loops, and streaming replay, see caching.
Thinking budgets
A request's thinking budget resolves to one of four settings: none,
low, medium, or high. Medium is the newest tier and fills the
gap between a cheap nudge and a full reasoning pass, which previously
meant choosing between spending almost nothing on reasoning and
spending a lot. Each setting maps onto whatever the destination
provider actually supports, so the same choice becomes an Anthropic
thinking budget, an OpenAI reasoning effort, or a Gemini thinking
budget without you changing anything at the call site. That is the
point of expressing it as a tier rather than a provider-specific
number: routing can move a request across providers and the intent
survives the move.
There is also an org-level auto mode. With auto on, the gateway picks the tier per request rather than the caller pinning one, which is usually what you want for mixed traffic where the caller cannot know in advance whether a given prompt deserves a reasoning pass. Every request records where its budget came from, whether the client asked for it, the org default applied, or auto derived it, so the choice stays auditable in the requests browser after the fact.
Budgets
Daily and monthly spend caps can apply per team, and the monthly cap can
also be set per account. Once a cap is hit the gateway returns 429
until the bucket resets: the daily bucket at midnight UTC, the monthly
one at the start of the next month. A per-key daily cap overrides the
team cap when it is set tighter.
Every 429 carries X-RateLimit-Scope naming which limit actually
fired. Scope values include rps, rpm, tpm, daily_budget,
monthly_budget, key_spend_ceiling, team_daily_budget,
team_monthly_budget, and org_inflight_cost. The backoff hints ride along
only where there is a clock to name: Retry-After plus
X-RateLimit-Reset on rps, rpm, and tpm -- rps is a one-second
window, not sixty -- and Retry-After alone on daily_budget,
pointing at the next UTC midnight. Do not write a
backoff loop that assumes a reset hint is always there. The scope
header is the useful piece: a client can tell a request-rate burst
apart from a blown monthly budget from the response alone, without
opening a support ticket to find out which knob it hit.
A per-request spend ceiling on cap:orchestrate routes is a separate
control from the budgets above: it checks a single request's worst-case
cost estimate before dispatch rather than a rolling per-team or
per-account bucket, and a breach returns a 4xx naming the estimate and
the cap rather than a 429 with an X-RateLimit-Scope value. See
capability aliases for the mechanics.
Billing errors
A 429 means one of your IQ-side caps fired. A 402 can mean exhausted provider credit or a subscription feature requirement. Read its error code and message. Add funds with your provider only when the error identifies provider credit. Check your IQ plan when it identifies a subscription requirement.
When every model in the fallback ladder fails because your own
provider key has run out of credit, the gateway returns 402 with an
actionable message naming the dead provider, of the form
Provider credit exhausted on your BYOK key for <provider>; add credits with your provider or configure another provider. It also
raises a billing alert in the dashboard's live activity feed, so an
operator sees it in the surface they already watch rather than by
reading logs after the fact.
Gateway API model usage is billed by your connected providers. An IQ subscription requirement is separate from provider credit.
Thinking-budget report
Thinking can add output tokens to a request. Those tokens normally use the model's output rate. The thinking-budget report groups spend by team and complexity tier so you can see where reasoning costs accumulate.
Note that this report groups by the complexity tier the gateway
assigned the request, which is a different axis from the four thinking
budget settings above. A request assigned complex may still have run
with a low budget if the caller pinned one, and a request assigned
simple under auto mode will normally have drawn none or low.
Read the report as where your spend concentrates by workload shape,
and the per-request budget source in the requests browser as why any
single request cost what it did.
The report groups spend by team and then by complexity tier, where the
tier is one of simple, medium, or complex.
Endpoint
GET https://gateway.iq-routing.com/admin/billing/thinking-report
?org_id=<uuid>
&period_start=2026-04-01
&period_end=2026-04-30
Authorization: Bearer <session token>
Requires owner or admin role. Cross-org probes return 404. The
response carries X-Request-Id, like every gateway response, for
correlating a specific pull; see API reference
for the error envelope shape returned on a non-2xx status.
A sample response:
{
"org_id": "org_5d9f...",
"period_start": "2026-04-01",
"period_end": "2026-04-30",
"total_tokens": 18470000,
"total_cost_usd": 924.50,
"by_team": [
{
"team_id": "team_a1b2...",
"team_name": "Research",
"total_tokens": 14820000,
"total_cost_usd": 741.00,
"by_tier": [
{"tier": "simple", "tokens": 320000, "cost_usd": 16.00},
{"tier": "medium", "tokens": 4500000, "cost_usd": 225.00},
{"tier": "complex", "tokens": 10000000, "cost_usd": 500.00}
]
},
{
"team_id": "team_c3d4...",
"team_name": "Support",
"total_tokens": 3650000,
"total_cost_usd": 183.50,
"by_tier": [
{"tier": "simple", "tokens": 2400000, "cost_usd": 60.00},
{"tier": "medium", "tokens": 1250000, "cost_usd": 123.50}
]
}
]
}
Dashboard
The Billing tab carries a thinking-budget report tile
rendered as a stacked bar chart. Each bar is one team; the bar
segments are the three tier buckets (simple, medium, complex).
Hovering a segment shows per-team-per-tier token count and dollar
cost.