Skip to content
IQ

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.