Research-backed calculator guide

Claude count_tokens vs Billed Usage: Build a Variance Budget

Learn why Claude count_tokens can differ from billed usage and build a request-level variance budget for ordinary input, cache creation, cache reads, output, and non-billed residuals.

Why count_tokens and billed usage are different measurements

count_tokens answers a narrow question: how many input tokens would this particular message request contain for this model? The API reference describes a POST /v1/messages/count_tokens endpoint that accepts the message shape and returns an input_tokens value without creating a message. The request can include messages, a system prompt, tools, images, and documents. ^[2] It does not generate an answer, so it has no output-token result to report.

A completed Messages response answers a different question: what token quantities did the service record while processing and returning this response? Its usage object includes ordinary input and output fields, as well as prompt-cache creation and cache-read fields when applicable. Anthropic documents total input as the sum of input_tokens, cache_creation_input_tokens, and cache_read_input_tokens. It also says the counts will not map one-to-one to the visible text because the service transforms the request for the model and parses the model output. ^[3]

That difference in measurement scope explains several common false comparisons:

• Comparing a preflight input count with input_tokens + output_tokens mixes input and output.
• Comparing count_tokens with only usage.input_tokens can omit cache creation or cache-read tokens.
• Counting a simplified prompt and then sending a request with tools, images, documents, or a different system prompt changes the request.
• Reusing a count measured for one model on another model is unsafe because tokenization is model-specific. AWS makes the same point for its Claude integrations and says the count returned by its CountTokens operation is tied to the input that would be charged for that inference request. ^[4]
• Assuming cache markers in a preflight request prove that a cache hit will occur is incorrect. Anthropic's guide says token counting provides an estimate without using caching logic; caching occurs during actual message creation. ^[1]

A useful ledger therefore has at least two timestamps: preflight_checked_at and message_completed_at. It should also retain the provider, endpoint, model ID, region or service path, request fingerprint, count result, usage object, pricing version, and classification of any residual. This makes a difference explainable later instead of turning a dashboard number into an untraceable guess.

A variance-budget model for Claude requests

Use this sequence for every request class you care about.

1. Fingerprint the count request. Serialize the exact model, system content, messages, tool definitions, image or document blocks, and cache-control blocks used for the preflight call. Normalize only fields that your implementation has proven irrelevant. Hash the canonical form and keep the original request under an appropriate retention policy.
2. Record the preflight estimate. Store count_tokens.input_tokens as an input estimate, with the model ID and endpoint. Do not call it a billed total, and do not use it as an output estimate.
3. Fingerprint the actual message request. Before sending, compare the request body that will create the message with the body used for counting. A retry, middleware injection, changed system prompt, altered tool schema, or different model should create a new preflight record.
4. Join the completed usage object. Persist the raw usage fields. Keep ordinary input, cache creation, cache read, and output as separate columns even if your first report only displays a total.
5. Calculate a residual. Compare like with like. The simplest input residual is preflight_input_estimate - (input_tokens + cache_creation_input_tokens + cache_read_input_tokens). A positive residual means the preflight number was larger than the recorded billed input components. A negative residual means the completed input components exceeded the preflight number.
6. Classify, do not hide. Label each difference as request drift, cache-state difference, model or endpoint mismatch, expected estimate noise, non-billed system-added tokens, or unresolved. A classification can be provisional and revised when a later provider export becomes available.

The residual is a diagnostic budget, not permission to invent an explanation. If the absolute residual is material, stop aggregating it into a monthly average and sample the raw request pair. A small difference can be expected because the provider describes the count as an estimate, but “small” is a monitoring threshold you choose from your own workload rather than a universal guarantee.

Worked example: one request, two ledgers

The following example uses an illustrative rate card, not a current Anthropic quote. Rates are shown in USD per 1 million tokens so the units are explicit. Replace them with the model, channel, region, cache TTL, and contract rates that actually apply to your account. The example assumes the same request fingerprint was used for counting and message creation, and that there was no cache read.

The input variance is 800 / 12,400 = 6.45% relative to the preflight estimate. In this deliberately simple case, the positive residual is a candidate for non-billed system-added tokens or estimate noise, but it is not proven by arithmetic alone. The operator should confirm that the request body, model, and endpoint were identical and that the usage record is complete. If the request had changed, the correct label would be request drift. If it had a cache read, the correct ledger would include that field instead of forcing it into ordinary input.

The table also shows why a single “tokens used” number is inadequate for cost forecasting. The preflight count cannot know the generated output. The completed input total contains multiple billing classes with potentially different rates. Even when the token total is close, the dollar total can move because the mix changes. A variance budget should therefore track both token variance and dollar variance.

A production implementation can calculate these fields as follows:

billed_input_tokens = input_tokens
                     + cache_creation_input_tokens
                     + cache_read_input_tokens

input_residual_tokens = preflight_input_tokens - billed_input_tokens

estimated_cost_usd = ordinary_input_tokens / 1e6 * ordinary_input_rate
                   + cache_create_tokens / 1e6 * cache_create_rate
                   + cache_read_tokens / 1e6 * cache_read_rate
                   + output_tokens / 1e6 * output_rate

Use a pricing snapshot ID with the rates. If a vendor changes a rate or your gateway applies a markup, the ledger can be recalculated without pretending the old estimate was a vendor invoice. If you route through AWS Bedrock, record that provider path separately: AWS documents both its bedrock-runtime CountTokens operation and a bedrock-mantle path for certain Claude models, with model and endpoint support varying by deployment. ^[4]

What to store for an auditable reconciliation

The minimum useful record is more than prompt_tokens. Store the request ID or correlation ID, provider, service path, model ID, account or workspace, region, API version, and the canonical request hash. Store the count response and timestamp separately from the message response. Keep the raw usage object, including null-versus-zero distinctions for cache fields, because an absent field and an explicit zero may have different meanings in an adapter.

Next, store the pricing context: currency, unit scale, ordinary input rate, cache-creation rate, cache-read rate, output rate, effective date, and whether each rate is a vendor quote, a negotiated contract value, or an internal estimate. Do not mix a public list price with an invoice total that includes taxes, credits, or gateway fees. A finance reconciliation should add those non-token adjustments in a separate layer.

Finally, store variance_status, variance_reason, and variance_owner. Suggested statuses are matched, expected_estimate_noise, request_drift, cache_state_changed, provider_path_mismatch, non_billed_system_tokens, and unresolved. Add a review threshold in tokens and dollars. For example, an engineering team might review any residual above 2% of preflight input or above $0.01 per request, but those are governance assumptions, not Claude guarantees.

This is where the AI API invoice reconciliation guide can complement the request ledger: the request-level record explains what happened, while the invoice workflow checks whether the provider's aggregate export and payment record agree. For broader unit economics, use the LLM cost calculator and keep provider-specific assumptions visible. The AI token cost calculator is useful when you need to compare ordinary input, output, and cached-token scenarios before sending traffic.

Limits, exclusions, and failure modes

This method reconciles token usage. It does not prove that an invoice is correct, and it does not account for every possible platform charge. Taxes, credits, subscription fees, marketplace adjustments, gateway markups, network charges, tool-provider charges, and human review belong in separate meters unless the provider explicitly includes them in the token usage record.

It also does not infer output length from count_tokens. Use a planned output budget only as a scenario assumption. The completed output_tokens field is the evidence for the generated side. Anthropic's Messages reference notes that output counts can be non-zero even when the visible response string is empty, so a UI that counts characters or words cannot replace usage data. ^[3]

Do not use an unrelated tokenizer as a proxy for Claude. A character heuristic or another provider's tokenizer may be useful for rough triage, but it should be marked as an estimate and never joined to an exact Claude usage row as if it were the same meter. For code, structured tool schemas, images, and documents, send the same content blocks to the provider count endpoint whenever the workflow requires a defensible estimate.

Count-token calls can also have operational limits. Anthropic documents separate rate limits for token counting and message creation, while AWS documents its own supported models, regions, permissions, and endpoint behavior. ^{[1] [4]} A failed or throttled preflight should be an explicit preflight_unavailable state. Do not silently substitute a stale count from another model or request.

If your system retries a message, assign each attempt its own correlation ID and usage record. A retry may be successful, partially streamed, or cancelled, and the aggregate cost can exceed the first attempt even when the user sees one final answer. Reconciliation should sum provider usage per attempt and then roll up by logical task, with duplicates visible rather than discarded.

FAQ

Is Claude count_tokens the exact number I will be billed?

No. It is an input-token estimate for the request shape submitted to the count endpoint. Anthropic says the count can differ by a small amount from the input used when creating a message, and system-added tokens may appear in counts without being billed. Use the completed usage object for the actual request-level token record. ^[1]

Does count_tokens include output tokens?

No. The count endpoint returns an input_tokens value. It does not run generation, so it cannot know the response's actual output length. Forecast output with an explicit scenario assumption, then reconcile to output_tokens after the message completes. ^{[2] [3]}

Should I compare count_tokens with usage.input_tokens only?

Only if you have confirmed that no cache creation or cache read occurred and you are intentionally comparing ordinary input. Anthropic defines total input as ordinary input plus cache creation and cache-read fields. Compare the preflight input with that sum, then keep each component for cost calculation. ^[3]

Why can two counts differ for the same text?

The model and request shape matter. A system prompt, assistant history, tool schema, image, document, cache marker, endpoint, or model change can alter the measured input. Even without an obvious change, the provider describes preflight counting as an estimate. Keep a canonical request hash and treat a mismatch as evidence to investigate, not as a rounding error by default.

Does a cache_control marker guarantee a cache hit?

No. The token-counting guide says counting provides an estimate without using caching logic; prompt caching occurs during actual message creation. The completed usage fields are the evidence for cache creation and cache reads. ^[1] A preflight request can preserve the intended cache markers, but the ledger should not book a cache-read rate until usage confirms it.

How should I handle Claude through AWS Bedrock?

Record Bedrock as a separate provider path and use the model's supported CountTokens route. AWS says CountTokens does not incur charges and that token counting is model-specific. It also documents different endpoint choices for models that are not supported on bedrock-runtime. ^[4] Do not merge a direct Anthropic count with a Bedrock usage row unless the request and accounting semantics are intentionally verified.