01 — Token Economics and Measurement

Summary

Pricing and feature claims are verified against live Anthropic documentation (URLs in the Verification ledger).

• Verified live pricing: Fable 5 $10/$50 per MTok in/out, cache read $1 (0.1×), 5-min cache write $12.50 (1.25×), 1-hour write $20 (2×); Sonnet 4.6 $3/$15; Haiku 4.5 $1/$5; Batch API 50% off everything. 1M-token context is now standard-priced on Fable 5/Opus 4.8/Sonnet 4.6 — the brief's assumption of a long-context premium is outdated.
• The exchange rates that decide everything: 1 output token = 5 input tokens = 50 cache-read tokens. Thinking bills as output. A token avoided in output is worth 50× a token avoided in cached input.
• Tokenizer divergence is official, but content-specific: Anthropic documents that Opus 4.7+/Fable 5 use a new tokenizer producing "roughly 30%" more tokens for the same text. Local follow-up shows the premium is strong on English/ASCII prose, but code/CJK can be near-neutral. Cross-model dollar math must count the target corpus, not just prices.
• Ground truth lives in the API usage object (input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens); count_tokens is free (rate-limited 2,000–8,000 RPM by usage tier) and is the experiment instrument; Claude Code exposes /cost, /context, and full OTel metrics (claude_code.token.usage by type/model/agent).
• Modeled heavy-day profile (basis for stack math): the $17 floor variant is ~25k uncached input, ~400k cache-write, ~5.5M cache-read, ~125k output tokens on Fable 5; the $22 working variant in 15 — Composed Stacks scales this to six sessions. The measured split is profile-specific; the stable invariant is that cache reads dominate token volume while output + cache writes dominate dollars.

---

Question and scope

Which token classes drive provider cost, and how should measurements separate uncached input, cache writes, cache reads, thinking, and visible output?

Method

4. Measurement instruments (how to see spend at all)

API usage object — the ground truth. Every Messages response carries usage.input_tokens (uncached), usage.cache_creation_input_tokens (further broken down in usage.cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens), usage.cache_read_input_tokens, usage.output_tokens (visible + thinking + tool_use blocks). Total prompt size = input + cache_creation + cache_read. All dossier arithmetic uses these fields.

count_tokens — the free experiment instrument. POST /v1/messages/count_tokens accepts messages/system/tools/thinking exactly like a real request. Verified live (token-counting page): free, separate rate limit (named usage tiers Start 2,000 / Build 4,000 / Scale 8,000 RPM), counts are an "estimate" that "may differ by a small amount" (system-added tokens are not billed), it never touches the cache, and thinking blocks from previous assistant turns are ignored — matching the production rule that prior-turn thinking is stripped from billed context (a built-in, automatic saving documented in 12 — Provider-level features, current and beta).

Claude Code surfaces.

• /cost — per-session totals; /context — live context-window decomposition (system prompt, tools, MCP, memory files, messages). Quick, but session-scoped and manual.
• OpenTelemetry (CLAUDE_CODE_ENABLE_TELEMETRY=1, OTLP exporters): metrics claude_code.token.usage (attribute type ∈ input / output / cacheRead / cacheCreation, plus model, and skill.name / plugin.name / agent.name for attributing spend to skills, plugins, and subagents), claude_code.cost.usage (USD), claude_code.active_time.total, plus events: claude_code.api_request (per-call tokens+cost), claude_code.compaction, claude_code.tool_decision. OTEL_LOG_RAW_API_BODIES=1 captures full request/response bodies (60 KB truncation; thinking content is always redacted). This is the right backbone for a personal token dashboard; the per-agent.name attribution is exactly what's needed to measure subagent economics (11 — Multi-agent protocols and subagent compression). (code.claude.com/docs/en/monitoring-usage.)
• Session JSONL transcripts (~/.claude/projects/<project>/<session>.jsonl) — per-call usage including cache fields. Two traps found locally (02 — Baseline audit of the research environment): the same message.usage repeats on every content-block line (dedup by message.id or overcount ~3×), and thinking text is redacted (thinking: ""), so thinking must be inferred as output_tokens − count_tokens(visible blocks).
• Console usage pages / ccusage-style analyzers — covered with the market scan in 03 — Prior art and market scan; JSONL-based analyzers inherit both transcript traps above.

Findings

1. Verified price table (live)

From the live pricing page (platform.claude.com/docs/en/about-claude/pricing):

All $/MTok. Multipliers are uniform across the lineup: cache write 1.25× (5-min TTL) or 2× (1-hour TTL), cache read 0.1×, batch 0.5× — and they stack (batch + caching compose).

Claude Sonnet 5 figures are introductory pricing through 2026-08-31, after which it moves to $3 input / $15 output with the standard multipliers.

Verified side facts that matter for optimization math:

• Long context: Fable 5, Opus 4.8/4.7/4.6, Sonnet 4.6 include the full 1M-token window at standard pricing — "a 900k-token request is billed at the same per-token rate as a 9k-token request" (pricing page). No premium tier to engineer around anymore; the cost of a bloated context is linear, not super-linear — but quality degradation with context length is not (see 06 — Context architecture — what enters the window at all).
• Fast mode (research preview): Opus 4.8 at $10/$50 — i.e., Opus-fast costs exactly Fable 5 list. Speed, not savings.
• US data residency (inference_geo: "us"): 1.1× on every token class. Don't set it idly.
• Tool-use system prompt is billed and model-specific: 290 tokens on Opus 4.8, 497 on Sonnet 4.6/Opus 4.6, 496 on Haiku 4.5 (auto choice; pricing page table). Local measurement on Fable 5: ~318 tokens with one minimal tool. Any non-empty tools array pays this once per request.
• Server tools: web search $10/1,000 searches; web fetch free beyond tokens; bash tool +245 input tokens; text editor tool +700 tokens (Claude 4.x).

2. The exchange rates — why token classes are different currencies

On Fable 5, per token:

Consequences, mechanical but decisive:

1. Output discipline is worth 50× cache-read discipline per token. A technique that trims 1,000 output tokens equals one that trims 50,000 cache-read tokens. This single ratio reorders most folklore tier lists, which obsess over input-side prompt slimming.
2. Thinking is output. Locally measured at 54.8% of output tokens in a max-effort session (02 — Baseline audit of the research environment). Any output-side technique that doesn't touch thinking (all style layers) caps out at the visible share.
3. Cache reads are cheap, not free — and they're the volume king. 92.8% of prompt-side tokens in the measured workload were cache reads; at 0.1× they were still a major dollar line (32% in that session; 21% in an independent output-heavy session), because the entire conversation prefix is re-read on every API call. Context mass costs ≈ prefix_tokens × 0.1× × calls_per_session, so a 2,738-token always-on CLAUDE.md chain costs ~52k cache-read tokens over a 19-call session — plus its share of cache writes whenever the prefix re-forms.
4. Break-even arithmetic for cache writes: 5-min write (1.25×) pays for itself after one read within TTL (1.25 + 0.1 < 2 × 1.0). 1-hour write (2×) needs ≥2 reads (confirmed in live docs: "caching pays off after just one cache read for the 5-minute duration… after two cache reads for the 1-hour duration"). Re-deriving the idle-gap economics from these multipliers is done in 07 — Caching exploitation.

3. Tokenizer divergence — tokens are not a stable unit across models

Official, from the live docs:

The newer tokenizer (Opus 4.7 and later) "produces approximately 30% more tokens for the same text. The exact increase depends on the content and workload shape. Claude Sonnet 4.6 and earlier models use the previous tokenizer." (pricing page; Claude Sonnet 5 is listed among the new-tokenizer models)

"Claude Fable 5 … uses the tokenizer introduced with Claude Opus 4.7, which produces roughly 30% more tokens than models before Claude Opus 4.7 for the same text." (token-counting page)

Local confirmation (02 — Baseline audit of the research environment): identical text counts +15% (Python code) to +38% (English prose) on Fable 5 vs Sonnet 4.6; CJK diverges least.

Implications:

• Cross-tier routing saves more than list prices imply. Moving prose-heavy work Fable 5 → Sonnet 4.6 cuts price per token 3.3× and tokens per text ~1.2–1.4×: effective ~4–4.6× on input classes. Quantified per task class in 10 — Model routing and tiered delegation.
• Never reuse token counts measured on one tokenizer to budget another (docs say this explicitly for migration). All measurements in this dossier name the model they were counted on.
• Tokens/char measured locally on Fable 5: ~2.3–3.4 for English/markdown, ~1.4–1.6 for CJK, more granular tables in 05 — Tokenizer arbitrage.

5. The modeled session profile (basis for all stack arithmetic)

Measured base (this environment, 02 — Baseline audit of the research environment): one heavy orchestration session = 19 API calls; 5,475 uncached input / 84,693 cache-write / 1,167,417 cache-read / 26,977 output tokens (54.8% thinking at max effort).

HEAVY-DAY profile. Two internally-consistent variants are used in this dossier — a $17 floor (5 sessions, 45% thinking — the table below) and a $22 working figure (6 sessions, 55% thinking) that the area files (04–13) and the composed stacks (15) adopt; both scale the same measured session, and every stack multiplier is unchanged across them. Table for the $17 floor (assumption-explicit scaling; multiply rows by 1.2 and shift the thinking split for the $22 variant):

Assumptions recorded: (a) main-loop only — subagent/workflow fan-out multiplies this profile and is modeled separately in 11 — Multi-agent protocols and subagent compression; (b) cache behavior healthy (92.8% read share measured) — a session with idle gaps >5 min degrades writes into the dominant line; (c) thinking share 45% (measured 54.8% at max effort; lower effort settings reduce it — sweep in 09 — Output discipline and structured generation). Sensitivity: at 55% thinking the output rows become $3.44/$2.81 reversed; total unchanged. At a 70% cache-read share (sloppier sessions), day cost rises ~$3–4 from extra writes.

The $/task metric (brief §4). All stack claims in 15 — Composed Stacks: Conservative / Aggressive / Unbelievable use: Nx = (baseline $/completed task) ÷ (optimized $/completed task) at statistically indistinguishable success on the validation suite (16 — Validation Harness: the No-Quality-Loss Proof Protocol). With ~10 completed tasks/heavy day, baseline ≈ $1.70/task on this profile.

Implications for jackin❯

For jackin❯, the token economics and measurement evidence identifies which mechanisms are safe to adopt directly and which still require workload-specific validation.

Limitations and unknowns

Quantitative conclusions are workload- and model-specific. Re-measure volatile provider inputs and validate transfers on representative jackin❯ tasks.

Sources

Related work

• Token-optimization techniques dossier
• Validation harness
• Context engine