How Claude Token Billing Works: Input, Output, and Cache Costs

June 23, 2026 · updated June 25, 2026 · How Claude Actually Works (part 26)

▶ Watch on YouTube & subscribe to The Stack Underflow

Every Claude API invoice reduces to exactly three line items: input tokens, output tokens, and cached tokens. Most developers who complain about unexpected bills are usually mis-diagnosing the problem — “switch to a cheaper model” is instinct, but it is usually the wrong lever. The real money is in the prefix you re-send on every agent loop, the 8 KB tool payload you never read again, and output tokens that cost five times what input tokens do.

Understanding the cost anatomy before you build an agent is the difference between a demo that costs pennies and a production system that triggers billing alerts on week one.

The one-sentence version: Three buckets — input, output, and cached tokens — drive every bill; output costs roughly 5x input; agent loops compound the prefix cost on every iteration; and three targeted fixes (cache the prefix, prune tool outputs, route by model tier) eliminate most runaway spend.

The Three Billing Buckets

Input tokens are every token the model reads before it starts writing: system prompt, conversation history, tool definitions, tool results. Output tokens are every token the model generates in response. Cached tokens are input tokens that were found in the prompt cache and served from storage rather than processed from scratch.

That is the complete list. Nothing else appears on an Anthropic invoice.

The write cost on caching is a one-time overhead. The read cost on every subsequent cache hit is where the savings stack up — and across an agent loop with many iterations, that compound discount is dramatic.

The 5x Output Multiplier

The price ratio between output and input is not arbitrary. Generating a token requires a full forward pass with attention over the entire current context; reading a token in input only requires that pass once per batch. Providers price accordingly. On current Claude models (verified June 2026):

Claude Haiku 4.5   — $1.00 input  /  $5.00 output  per million tokens
Claude Sonnet 4.6  — $3.00 input  / $15.00 output  per million tokens
Claude Opus 4.8    — $5.00 input  / $25.00 output  per million tokens
Claude Fable 5     — $10.00 input / $50.00 output  per million tokens
                     (re-verify at platform.claude.com before recording)

The 5x ratio holds across all tiers. A model that generates a 2,000-token answer where 400 tokens would have served produces the equivalent spend of 10,000 input tokens — 8,000 of budget spent entirely on output verbosity. Conciseness is a performance optimization, not just a style choice.

A practical consequence: if you are running an evaluator, a yes/no classifier, or a reformatter, you are probably paying 5x for a token or two of output. Those tasks belong on a cheaper tier and should be prompted for extreme brevity.

The Agent Loop Multiplier

Single-turn calls are cheap. Agent loops are where cost surprises arrive.

The model has no memory between API calls. It is stateless. When an agent loops — reads a tool result, decides the next step, calls another tool — it must resend the full context as a prefix on every iteration: system prompt, all prior tool calls, all prior results. The prefix grows with every lap.

Iteration 1:  [sys] + [Q]                                       → response (small prefix)
Iteration 2:  [sys] + [Q] + [tool_1] + [result_1]              → response (medium prefix)
Iteration 3:  [sys] + [Q] + [tool_1] + [result_1] + [tool_2]
              + [result_2]                                       → response (large prefix)
...
Iteration N:  [sys] + [Q] + [all prior turns]                   → response (N-1 prefixes billed)

If the loop runs N times, the system prompt is billed N times at full input rate. Tool result 1 is billed N-1 times. Tool result 2 is billed N-2 times. The cumulative cost scales quadratically with loop depth when context grows.

This is why agent demos are cheap (two or three iterations, small outputs) while agent products are not (ten to fifty iterations, context growing every lap).

Cost per iteration in a naive agent loop
─────────────────────────────────────────
Iteration  1:  $0.003   (small prefix)
Iteration  5:  $0.015   (prefix 5× larger)
Iteration 10:  $0.030   (prefix 10× larger)
Iteration 50:  $0.150   (prefix 50× larger)

Total 50-iteration loop (no caching): ~$3.80
Same loop with cached prefix:          ~$0.60 (84% reduction)

The Three Cost Leaks — and Their Fixes

Leak 1: Uncached Prefix Repaid Every Iteration

The problem: Your system prompt and initial context are identical on every iteration. Without caching, every iteration pays full input-token price for those identical tokens.

The fix: Mark the stable prefix with cache_control breakpoints. Every subsequent call that hits the cache pays approximately 0.1x standard input rate for those tokens. Across ten iterations, you turn nine full-price prefix bills into nine cache reads — typically a 70–90% reduction in prefix input cost.

messages_api_request = {
    "model": "claude-opus-4-8",
    "system": [
        {
            "type": "text",
            "text": LONG_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}   # mark stable prefix
        }
    ],
    "messages": conversation_history
}

Two TTL options exist as of 2026: 5 minutes (default, 1.25x write cost) and 1 hour (2x write cost, same 0.1x read). Choose based on your inter-call cadence. For tight agent loops the 5-minute TTL is usually sufficient. Note: Anthropic moved to workspace-level cache isolation in February 2026 — cache hits are scoped per workspace, not per organization.

For the full implementation guide, see Prompt Caching: Cut Your AI Bill.

Leak 2: Tool Output Accumulating in Context

The problem: A tool returns 6 KB of JSON. You append it directly to the conversation. Now it is part of the permanent prefix for every subsequent iteration — billed at full input rate, every lap, even though nothing downstream needs most of it.

The fix: Extract only what the next reasoning step actually needs before appending to context. If a web search returns full HTML but the agent only needs the article title and two key facts, slice those three fields and discard the rest.

Tool returns: 6,000 tokens of raw JSON
                    ↓
     [Extract: 3 fields needed downstream]
                    ↓
Append to context: 80 tokens

Savings per iteration: 5,920 tokens × (N remaining iterations)

Rules of thumb:

• If a tool result is larger than 500 tokens, ask whether all of it needs to survive in context past the current turn.
• If raw output was needed once but is not needed again, drop it from context after processing.
• For large payloads (database dumps, long API responses), store them externally and keep only a pointer plus extracted fields in context.

For a full treatment of context pruning strategies, see Context Engineering: Pin, Summarize, Prune, Compact.

Leak 3: Top-Tier Model for a Bottom-Tier Task

The problem: One API client, one model ID, all calls routed there. The classifier returning positive/negative, the reformatter fixing punctuation, the yes/no gate — all of them hitting Opus 4.8 at $5/$25 per MTok.

The fix: Tier routing — map task complexity to model capability before the call goes out. The cost difference across tiers is roughly 5x between adjacent rungs and 25x from Haiku to Opus. Routing even half your calls to a smaller model can cut your bill substantially.

def route_to_model(task_type: str) -> str:
    # These tasks need no frontier reasoning
    simple_tasks = {"classify", "reformat", "yes_no", "extract_field", "validate"}
    # These tasks benefit from deeper reasoning
    complex_tasks = {"plan", "synthesize", "reason_multi_step", "creative_generate"}

    if task_type in simple_tasks:
        return "claude-haiku-4-5"      # $1/$5 per MTok
    elif task_type in complex_tasks:
        return "claude-opus-4-8"       # $5/$25 per MTok
    else:
        return "claude-sonnet-4-6"     # $3/$15 per MTok — capable middle ground

Quality and cost are not always correlated. A classifier asked to output positive or negative produces the same output quality on Haiku as on Opus — at 25x lower cost. Reserve frontier models for tasks that genuinely require frontier reasoning.

The Full Cost Map

A single request
├── Input tokens      (1x)     system prompt + history + tool results
├── Output tokens     (5x)     model-generated response
├── Cache write       (1.25x)  first call to store prefix in cache
└── Cache read        (0.1x)   subsequent calls hitting that cache entry

An agent loop (N iterations, naive)
├── Prefix repaid N times at full input rate   → Leak 1: fix with cache_control
├── Tool output grows prefix each iteration    → Leak 2: fix with extract + prune
└── All calls at top-tier rate                 → Leak 3: fix with tier routing

Stack the fixes
├── Cache the stable prefix    (typically ~80-90% reduction on prefix input cost)
├── Prune tool outputs         (cut context growth by 80-90% per tool call)
├── Route cheap tasks to Haiku (5-25x cheaper per token on simple tasks)
└── Batch offline jobs         (50% off standard rates via Message Batches API)

A Fourth Lever: The Batch API

For any task where latency does not matter — offline evaluation, document processing, nightly analytics, content generation pipelines — the Message Batches API processes requests asynchronously and returns results within 24 hours at exactly 50% off standard token prices. There is no quality difference; only timing.

Batch and caching stack. A cached batch request on Haiku 4.5 brings effective input cost to approximately $0.05 per million tokens — a 95% reduction from the standard $1.00 rate. For high-volume offline jobs, this combination is the most aggressive cost reduction available.

Practical Guidance: Before You Ship

1. Profile your loop depth. How many iterations does your agent typically take? Three? Fifteen? The multiplier is real — know it before you size your budget.
2. Add cache_control to your system prompt on day one. It is two lines of code. The ROI is immediate on any loop deeper than two iterations.
3. Log tool output sizes. Add instrumentation to surface which tools return large payloads. Prune the worst offenders first.
4. Audit your model routing. List every call type in your agent. Mark which ones could be handled by Haiku. Route and measure — quality rarely regresses on simple tasks.
5. Date your prices. Prices drift. The figures above are accurate as of June 2026 (verified at platform.claude.com/docs/en/about-claude/pricing). Anchor cost estimates to a date and re-verify before making architectural decisions.

Common Misconceptions

“Output is cheap — prompts are long so that’s where the cost is.” Output tokens cost roughly 5x input tokens on every current Claude model. A short prompt producing a long answer is more expensive than a long prompt producing a short answer, token-for-token. Verbose model output is a cost driver, not a neutral side effect.

“My agent only loops ten times so the cost is bounded.” The prefix grows on every iteration. Iteration 10 sends the system prompt plus nine rounds of tool calls and results. The cost per iteration rises as the loop progresses — it does not stay flat. The total cost scales with the area under the growing-prefix curve, not the number of iterations alone.

“Caching is for static websites, not agents.” Prompt caching was designed precisely for the agent loop pattern. The system prompt and initial few-shot examples in an agent are exactly the kind of stable, high-reuse prefix that makes caching valuable. Caching is most effective in loops, where the same prefix is re-billed on every iteration.

“Just use the best model and your outputs will be better.” Quality and cost are not always correlated. A classifier returning positive/negative, a field extractor, a format normalizer — these produce identical quality on Haiku as on Opus. Routing every call to the top tier introduces cost without introducing quality for these task types.

Frequently Asked Questions

How do I know which model tier to use for a given task? Start by characterizing the task type. Does it require multi-step reasoning, nuanced judgment, synthesis across a long context, or creative generation? Use a top-tier model. If the task is a lookup, classification, extraction, or formatting pass that a clear prompt can fully specify, start with Haiku and escalate only if output quality is insufficient. Most pipelines have a mix — profile each step independently rather than defaulting one model for all calls.

Does prompt caching work automatically, or do I need to configure it? You need to configure it. Add cache_control: {"type": "ephemeral"} to the content blocks you want cached. The cache is not automatic. Two TTL options are available as of 2026: the default 5-minute TTL (1.25x write cost, 0.1x read cost) and an extended 1-hour TTL (2x write cost, 0.1x read cost). Note that cache entries are now scoped per workspace, not per organization, following a February 2026 change. Full implementation is covered in Prompt Caching: Cut Your AI Bill.

What tool outputs should I worry about pruning? Any tool result larger than approximately 500 tokens that will survive in context for more than one subsequent iteration. Web search results, database query responses, file reads, and API payloads are the common offenders. Before appending a tool result, ask: what is the minimum information the next reasoning step actually needs from this? Extract those fields; discard the rest.

If cached tokens are 90% cheaper, why not cache everything? Cache hits only occur when the exact stored token sequence appears at the same position in the request. Only the stable, non-varying prefix of your prompt can realistically be cached — user queries, dynamic data injections, and per-call variables cannot be cached because they change on every call. There is also a write cost on the first cache population. Caching pays off when the same prefix is reused many times, which is the agent loop pattern. Caching arbitrary or one-off content does not pay back the write overhead.

Can I combine the Batch API discount with prompt caching? Yes. Batch processing (50% off) and prompt caching (90% off repeated input) stack. The savings apply independently to their respective token categories. A cached batch request on Haiku 4.5 achieves effective input cost around $0.05/MTok — 95% below the standard rate. Best suited for high-volume offline workloads where a few hours of latency is acceptable.

Does model tier affect context window size? Yes. As of June 2026: Opus 4.8, Opus 4.7, Sonnet 4.6, and Fable 5 all support a 1 million token context window at standard pricing with no long-context surcharge. Haiku 4.5 supports 200K tokens. When your task requires long-context reasoning, Sonnet 4.6 offers the most cost-effective access to a 1M context window at $3/$15 per MTok.

Where This Fits in the Series

This tutorial is part of How Claude Actually Works, a developer-focused course tracking the context, reliability, and cost planes through every major concept in Claude’s architecture. The cost plane starts here: once you have internalized how tokens work and how the context window fills, this tutorial translates those abstract counts into dollars. The two fixes that interact most directly with cost — caching and context pruning — are each covered in dedicated tutorials: Prompt Caching: Cut Your AI Bill and Context Engineering: Pin, Summarize, Prune, Compact. The series closes with Production Claude Agent Architecture, where all three planes — context, reliability, and cost — come together in a real system design. Browse all tutorials to follow the full sequence.