Claude API Pricing Explained: How Billing Actually Works

If you've ever stared at a Claude API bill and wondered why the number doesn't quite match your back-of-envelope estimate, you're not alone. Claude API pricing looks simple on the surface — pay per token, input and output priced separately — but the actual billing pipeline has a few moving parts most docs gloss over: how a request gets estimated before it runs, how it gets reconciled after, and what happens when the call fails halfway through.

This post breaks down the mechanics so you can reason about your own bill instead of guessing. It's not a price list — for current per-model numbers, always check /pricing, since token prices move and any number we typed here would go stale.

The two numbers that drive every bill: input and output tokens

Claude API pricing, like most LLM APIs, is metered on two separate token counts:

• Input tokens — everything you send: the system prompt, conversation history, user message, and any tool definitions or context you attach. This is usually the larger number in multi-turn or RAG-style workloads, because you're re-sending prior context on every call.
• Output tokens — what the model generates back. This is typically smaller than input for chat-style usage, but it dominates cost for long-form generation, summarization-to-length, or reasoning-heavy tasks that produce extended output.

Input and output tokens are priced independently, and the rate for output tokens is generally higher than input — generation is more expensive to serve than reading context. That asymmetry matters when you're estimating cost: a request with a huge system prompt but a one-line answer bills very differently from a short prompt that triggers a long response.

The practical implication is that "cost per request" isn't a single number — it's a function of your prompt shape. Two apps calling the same model can have wildly different unit economics depending on how much context they carry per turn and how verbose the responses are. The live per-model input/output rates (priced per 1M tokens) are always on /pricing — that's the same table the billing system reads from, so it never drifts out of sync with what you're actually charged.

The billing pipeline: pre-hold, settle, refund

Where most explanations stop is "pay per token." What actually happens on the gateway side of a request is a three-step pipeline:

1. Pre-hold on request start

When a request comes in, the gateway doesn't know the exact final token count yet — the response hasn't been generated. So it takes a pre-hold: an estimated deduction against your balance, sized to cover a reasonable worst case for that request. This is what protects your balance from being spent past zero by concurrent in-flight requests — without some form of reservation, nothing would stop you from firing off ten parallel calls that each pass a balance check individually and then collectively overdraw.

2. Settle on real usage

Once the upstream provider returns a response, it comes back with the model's own token accounting — real input and output counts, not an estimate. The gateway settles the charge against that real usage: if the pre-hold overshot, the difference is released back to your balance; the amount actually deducted is always tied to what the provider reports, not to the earlier guess.

3. Refund on failure

If the upstream call fails — a 5xx from the provider, a timeout, anything that means you didn't get a usable response — the request is not billed. The pre-hold is refunded automatically. You don't file a support ticket for a failed generation; the accounting corrects itself as part of the same request lifecycle. This also applies as the gateway retries across channels: retries you never see happen behind a single client-facing call, and only a response that actually reaches you gets billed.

The net effect: your bill reflects real token usage, and failures cost you nothing. That's the whole model in one sentence, and it's worth internalizing because it changes how you think about retry logic in your own code — you generally don't need to build your own "don't bill me for that failed call" safety net on top, since it's already the default behavior.

How to estimate your own costs before you build

Since pricing is two independent per-token rates, estimating cost for a workload is mostly about estimating token volume accurately — the rate lookup is the easy part.

A workable estimation checklist:

1. Measure your actual prompt size, don't guess it. System prompt + few-shot examples + retrieved context + user turn, concatenated, then run it through a tokenizer (or just check the usage field on a real test call — see the streaming example below). Estimating tokens from word count is close enough for English prose but gets unreliable fast with code, JSON, or non-English text.
2. Account for conversation history growth. If you're re-sending prior turns on every call (the common pattern for multi-turn chat), input tokens grow roughly linearly with conversation length. A 10-turn conversation can cost several times more per call by the last turn than the first, purely from re-sent context — worth knowing before you assume a flat per-call cost.
3. Cap output length deliberately. Uncapped generation is the most common source of runaway output-token cost. If your use case has a natural output ceiling (a summary, a classification label, a short answer), set max_tokens to match it rather than leaving it high "just in case."
4. Multiply by real call volume, not peak-day volume. Token price × tokens per call × calls per day gets you a daily estimate; multiply that against your actual traffic pattern (including retries, if you retry client-side on top of the gateway's own retry behavior) rather than a single anecdotal test run.
5. Cross-check against the usage log, not your estimate. Once you're live, the usage log (Console → Usage) shows the real per-call model, prompt/completion token counts, and cost, exportable as CSV for offline reconciliation — that's the ground truth your estimate should converge toward, not the other way around.

For the actual per-token rates to plug into that math, use /pricing — it's a live table read from the same source the gateway bills against, so an estimate built on it won't drift from what you're charged.

Reading real usage off a streaming response

If you want to see the exact numbers a request settles against, ask for usage on the final chunk of a streamed response. Here's the shape of that call against an OpenAI-compatible gateway:

curl {GATEWAY_BASE_URL}/chat/completions \
  -H "Authorization: Bearer $APIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [{"role": "user", "content": "Summarize this in two sentences: ..."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Replace {GATEWAY_BASE_URL} with your deployment's gateway address (the base URL you configured when you created your API key — see /docs for where that comes from). With stream_options.include_usage set, the last chunk of the stream carries a usage object with real prompt and completion token counts — the same numbers the settlement step in the billing pipeline uses. That makes it a good sanity check in dev: run a representative request, read the final usage chunk, and multiply against the rates on /pricing to get an exact cost for that call instead of an estimate.

Model IDs like claude-sonnet-4-5-20250929 above come from the catalog — confirm the exact ID you need on /models, since catalog entries can change as new versions ship.

Why this design instead of flat per-call pricing

Some APIs bill a flat rate per call regardless of content length; Claude API pricing (and metered LLM APIs generally) bills per token because request cost genuinely varies by orders of magnitude depending on prompt and output size. A one-line classification call and a long document summarization call are not the same unit of work, and flat-rate pricing either overcharges the former or undercharges the latter.

The pre-hold/settle/refund pipeline is what makes token-metered billing safe to build on top of: you get accurate accounting (settled against real usage, not the estimate), protection against concurrent overdraft (the pre-hold), and no cost for failures that aren't your fault (automatic refund). Combined with a balance that doesn't expire and works the same way across every model in the catalog, the practical result is that you can budget in one balance instead of reconciling separate bills per provider.

Try it yourself

The fastest way to get a feel for real Claude API costs on your own workload is to run it. New accounts get trial credit automatically on signup — no credit card required — so you can send a handful of representative requests, read the real token usage back, and check the settled cost against /pricing before committing to an integration. Sign up and point your existing OpenAI-compatible client at the gateway to see your first real numbers.