🎯 This page is both a CCA exam reference and the source list for cost guardrails — the
numbered RULE boxes are written to be turned into
automated checks (e.g. in CostSherlock) later.
1 · THE COST MODEL What you actually pay for
Every /v1/messages call bills input tokens + output tokens, at different rates.
Four facts drive almost all cost decisions:
- Output costs ~5× input. Across the whole line-up (Opus $5→$25, Sonnet $3→$15, Haiku $1→$5, Fable $10→$50 per 1M), output is 5× the input rate.
- Thinking / CoT tokens are billed as output. Extended/adaptive thinking is the expensive kind of token.
- The API is stateless — you resend the entire message history every turn, so every token in
messagesis re-billed on every call. A long conversation pays for its whole past, repeatedly. - Tools + system are re-sent (and re-billed) every call too — unless a cache covers them.
Pricing & cache multipliers (the numbers to know)
| Model | Input $/1M | Output $/1M | Output ÷ Input |
|---|---|---|---|
| Claude Opus 4.8 / 4.7 | $5 | $25 | 5× |
| Claude Sonnet 5 | $3 | $15 | 5× |
| Claude Haiku 4.5 | $1 | $5 | 5× |
| Claude Fable 5 | $10 | $50 | 5× |
| Token class | Multiplier vs base input | usage field |
|---|---|---|
| Normal input | 1× | input_tokens |
| Cache read (hit) | ~0.1× — ~90% cheaper | cache_read_input_tokens |
| Cache write, 5-min TTL | 1.25× | cache_creation_input_tokens |
| Cache write, 1-hour TTL | 2× | cache_creation_input_tokens |
| Output (incl. thinking) | 5× (per table above) | output_tokens |
| Batch API | ~0.5× on input and output | — |
A cached prefix breaks even after just two requests:
1.25× + 0.1× = 1.35× vs 2×
uncached. Cache read is the single biggest lever on a repeated prefix. (Full mechanics:
Prompt Caching & Memory.)2 · COST ANTI-PATTERNS The ways teams overspend
| # | Anti-pattern | Why it costs | Fix |
|---|---|---|---|
| A1 | No prompt caching on a stable system prompt / tools / schema | The whole prefix is re-processed at 1× every call | Add cache_control on the last stable block |
| A2 | Cache-busting the prefix — a timestamp, UUID, or unsorted JSON inside the cached region | Prefix bytes change → miss → you pay the write premium and full input, every call | Move volatile data after the breakpoint; sort JSON keys |
| A3 | Carrying huge tool_result payloads in history forever | Stateless resend re-bills them every turn | Context editing (clear old tool uses) · compaction |
| A4 | Over-large model for the task (Opus for classification) | Paying 5× Haiku's rate for no quality gain | Model-tier by task; escalate only hard steps |
| A5 | Unbounded agent loop (no max_turns) | A stuck agent calls tools forever | Hard turn cap + graceful stop |
| A6 | Huge max_tokens / no output ceiling | Lets a response run long at 5× rate | Set the smallest max_tokens that fits |
| A7 | Thinking / high effort on trivial tasks | CoT tokens billed as output for no benefit | Low effort (or no thinking) for easy work |
| A8 | Prose when you need data | You pay output tokens for framing words | output_config.format + a tight schema |
| A9 | One request per item for bulk work | No batch discount, more overhead | Batch API (~50% off) for latency-tolerant jobs |
| A10 | Over-fetching context (whole schema / all docs) | Input tokens for content the task never needs | RAG / retrieve only what's relevant; slim tool defs |
| A11 | Cache breakpoint after the volatile part | Nothing stable precedes it → never caches | Order tools→system→messages; breakpoint after the big stable chunk |
| A12 | Letting the cache expire between calls (default 5-min TTL, sparse traffic) | Every call is a fresh write, never a read | 1-hour TTL if reuse is spaced; keep it warm |
| A13 | No streaming on long outputs | Request timeout → retry → pay twice | Stream; use get_final_message() |
| A14 | Duplicating the system prompt into each user turn | Re-billed as message input every turn, uncacheable there | Put durable instructions in system once, and cache it |
| A15 | Changing tools/system mid-conversation | Invalidates the whole downstream cache (cascade) | Keep tools/system byte-stable across the session |
The compounding trap: A2 + A3 together — a cache that never hits and a history that keeps
growing — means every turn re-processes a bigger prefix at full price. This is the most common runaway-cost bug in agents.
3 · MESSAGE JSON THAT ALWAYS COSTS MORE Same result, higher bill
These request shapes are strictly more expensive than an equivalent that returns the same answer. Each pair is ❌ costlier vs ✅ cheaper.
3.1 · Volatile data inside the cached prefix → cache never hits (A2)
❌ A timestamp sits in the cached system block, so its bytes change every call — permanent miss + write premium.
"system": [{ "type":"text", "text":"Current time: 2026-07-16T09:31:07Z. You are a support agent. <5000-token policy…>", "cache_control":{"type":"ephemeral"} # caches a prefix that changes every call → useless }]
✅ Static policy cached; the volatile time moves into the (uncached) user turn.
"system": [{ "type":"text", "text":"You are a support agent. <5000-token policy…>", "cache_control":{"type":"ephemeral"} # byte-stable → HIT at ~0.1× after the first call }], "messages":[{"role":"user","content":"[time: 2026-07-16T09:31:07Z] …"}]
3.2 · Big stable content with no cache_control → re-billed at 1× forever (A1)
❌ A large schema/tools re-sent every turn, uncached — full input price on every call.
"tools": [ …40 tool defs… ], "system": "…8K-token schema…" # no cache_control anywhere → 1× every single turn
✅ Same content, one breakpoint after the stable region → ~0.1× on every later turn.
"tools": [ …40 tool defs… ], "system": [{"type":"text","text":"…8K-token schema…", "cache_control":{"type":"ephemeral"}}] # covers tools+system (order: tools→system→messages)
3.3 · Huge tool_result kept in history → re-billed every turn (A3)
❌ A 30K-token API dump stays in
messages for the rest of the session — paid again on every subsequent call.
"messages":[ …, {"role":"user","content":[{"type":"tool_result", "tool_use_id":"t1","content":"<30K tokens of raw JSON>"}]}, … ]
✅ Clear stale tool results once they're no longer needed (context editing) — the dialogue stays intact.
# request context_management with clear_tool_uses_20250919 → old tool_results dropped, # conversation preserved. See the context-bloat cheat sheet.
3.4 · Oversized ceiling + thinking on a yes/no task (A6/A7)
❌ A trivial classification with room to ramble and forced deep thinking — output (incl. CoT) billed at 5×.
{"model":"claude-opus-4-8", "max_tokens":32000,
"output_config":{"effort":"high"}, "messages":[{…"Is this spam? yes/no"}]}✅ Small model, tight ceiling, low effort, structured answer.
{"model":"claude-haiku-4-5", "max_tokens":8,
"output_config":{"effort":"low",
"format":{"type":"json_schema","schema":{"type":"object",
"properties":{"spam":{"type":"boolean"}},"required":["spam"]}}}}3.5 · One call per item vs one batch (A9)
❌ 10,000 synchronous calls, full price, plus per-request overhead.
✅ One Message Batches job — ~50% off input and output, correlate results by
custom_id. Use it whenever latency isn't critical.4 · CoT & ADAPTIVE THINKING The expensive tokens
Extended thinking (chain-of-thought) is where cost quietly grows, because thinking tokens are billed as output (5×). Key facts for the exam and for guardrails:
- Adaptive thinking (
thinking:{"type":"adaptive"}) lets the model scale reasoning to the task — great for hard problems, but it means output (and cost) is variable. On Opus 4.8/4.7/Sonnet 5 the oldbudget_tokensis gone (a 400). - Effort (
output_config.effort: low / medium / high / xhigh / max) is your dial: lower effort → fewer thinking+output tokens → cheaper & faster. Match effort to difficulty; don't payhighfor a lookup. - Thinking on trivial tasks is pure waste — a classifier or extraction rarely needs it. Reserve it for multi-step reasoning, planning, hard reconciliation.
- Thinking blocks live in the response and, in agent loops, are appended back into
messages— so they add to the resent history too. Context editing can strip old thinking to stop paying for it every turn. - Verbose outputs multiply everywhere — a chatty final answer is 5× tokens on top of the thinking. Ask for the shortest useful answer; use schemas.
Exam trap: "raise the thinking budget to make it smarter/cheaper." Wrong on both —
budget_tokens
is removed (400) on current models, and more thinking is more output cost. Use adaptive thinking + the
effort dial, and only where reasoning is actually needed.5 · COST BEST PRACTICES The mirror image
- Cache the stable prefix — order
tools → system → messages, put the breakpoint after the largest byte-stable block, keep it byte-identical. (Mind the min-prefix floor: 1024 tokens on Opus 4.8/Sonnet 5, up to 4096 on Haiku 4.5 — below it, nothing caches.) - Keep the cache warm — reuse within the 5-min TTL; switch to the 1-hour TTL when calls are spaced (needs ≥3 reuses to beat 5-min).
- Trim context — RAG over whole-schema dumps; slim tool descriptions; context editing to drop stale tool results; compaction for very long chats.
- Right-size the model — Haiku for simple/high-volume, Sonnet mid, Opus for the hard step. Tier within an agent (cheap draft, expensive verify).
- Cap the output — smallest
max_tokensthat fits; structured outputs to kill framing tokens. - Match effort to difficulty — low effort / no thinking for easy tasks; reserve high/xhigh for genuinely hard reasoning.
- Batch the bulk — Message Batches API (~50%) for anything latency-tolerant.
- Stream long outputs — avoid timeout-driven retries (double billing).
- Bound the loop —
max_turns+ graceful stop. - Measure — read
usageevery call (input_tokens,output_tokens,cache_read_input_tokens,cache_creation_input_tokens); track cost/request & cache-hit-rate =cache_read / (cache_read + cache_creation + input_tokens).
6 · COST GUARDRAIL CHECKLIST The CostSherlock seed
Written as rules you can automate against a request payload + its usage response:
R1 · Uncached big prefix: IF
len(system)+len(tools) > min_prefix(model) AND no cache_control present → WARN (add caching).R2 · Cache miss on a stable prefix: IF prefix unchanged since last call AND
cache_read_input_tokens == 0 → FLAG a cache-buster (volatile field / unsorted JSON / breakpoint placement).R3 · Oversized model: IF task class ∈ {classify, extract, route} AND
model is Opus/Fable → SUGGEST Haiku/Sonnet.R4 · No output ceiling: IF
max_tokens unset or > task budget → WARN.R5 · Effort mismatch: IF
effort ∈ {high,xhigh,max} on a task class that doesn't need reasoning → SUGGEST lower effort.R6 · History bloat: IF any single
tool_result > N tokens AND it persists across > K turns → SUGGEST context editing.R7 · Prose where data is wanted: IF downstream parses the output AND no
output_config.format → SUGGEST structured output.R8 · Unbatched bulk: IF request rate is high AND latency SLA is loose AND not using Batch → SUGGEST Batch API.
R9 · Unbounded loop: IF agent loop has no
max_turns → BLOCK.R10 · Deprecated params: IF
budget_tokens / temperature / top_p present on a current model → BLOCK (400 anyway).7 · EXAM ONE-LINERS
• Output ≈ 5× input, and thinking counts as output — verbose reasoning is the expensive path.
• The API is stateless: every token in
• Cache read ~0.1×, write 1.25× (5-min) / 2× (1-hour); break-even at 2 requests.
• Batch API ~50% off input and output for latency-tolerant work.
• Control thinking with adaptive +
• The classic runaway bug: a cache that never hits + a history that never shrinks.
• The API is stateless: every token in
messages is re-billed every turn — trim history.• Cache read ~0.1×, write 1.25× (5-min) / 2× (1-hour); break-even at 2 requests.
• Batch API ~50% off input and output for latency-tolerant work.
• Control thinking with adaptive +
effort, never budget_tokens (400 on current models).• The classic runaway bug: a cache that never hits + a history that never shrinks.