Token Economics Best Practices

A field guide to keeping Claude API spend proportional to the value it delivers: pick the right model tier by default, cache what's reused, batch what can wait, and measure everything instead of guessing.

How to Use This List

Treat section A as the baseline every new feature should start from; sections B-D are levers to apply once volume justifies the engineering cost.
Don't apply every practice to every feature, a low-volume internal tool doesn't need a router or batch integration, match the investment to the volume.
Revisit this list whenever pricing changes materially, especially around known transition points like Sonnet 5's 2026-08-31 intro-pricing expiration.
Pair the model-tier practices with a written ADR so the default isn't just a convention nobody remembers agreeing to.

A - Model Selection

Default new features to Sonnet 5, not the strongest model. Sonnet 5 handles the large majority of everyday tasks well, and reaching for Opus 4.8 or Fable 5 "just in case" bakes in a 2.5x to 5x cost multiplier for capability most tasks don't need.
Reserve Opus 4.8 and Fable 5 for genuinely hard reasoning tasks. Multi-step reasoning under ambiguity, high-stakes trade-off analysis, and safety-critical judgment calls are where the premium tiers earn their cost; templated or pattern-matching work rarely is.
Route high-volume, low-complexity tasks to Haiku 4.5. Classification, extraction, and simple formatting tasks run well on the cheapest tier, and the savings compound fastest exactly where volume is highest.
Build a router once volume justifies it, not before. A classifier that sends SIMPLE tasks to Haiku and HARD tasks to Opus pays for its own engineering cost only above a certain volume threshold; below that, a flat default is the more efficient use of engineering time.
Never let model choice default to "whatever was used in testing." An explicit, documented default (see the ADR template) prevents cost decisions from being made by accident.

B - Prompt Caching

Cache any prefix reused more than once within its TTL window. The arithmetic break-even for prompt caching is low, often just the second reuse, so err toward caching stable, repeated content rather than skipping it.
Put the most stable content first, most volatile content last. Claude assembles the cached prefix in a fixed order (tools, then system, then messages); structuring content this way maximizes what a breakpoint can cover.
Never interpolate per-user or per-session data into a cached block. A username, timestamp, or session ID inside the cached prefix invalidates the cache on every single call, silently erasing the savings.
Choose TTL based on real request spacing, not habit. Bursty, closely-spaced traffic favors the cheaper 5-minute TTL; traffic with gaps regularly exceeding 5 minutes favors the pricier 1-hour TTL despite its higher write cost.
Build cached content from one shared constant, not scattered inline literals. Even semantically identical text can fail to match byte-for-byte if it's rebuilt inconsistently across call sites, which silently breaks cache hits.
Monitor cache_read_input_tokens vs cache_creation_input_tokens in production. The theoretical break-even calculation only matters if real traffic is actually clearing it; log both fields and watch the ratio over time.

C - Batch Processing

Route any latency-tolerant, high-volume workload through the Batch API. Nightly reports, bulk classification, and offline dataset processing rarely need a synchronous response, and the roughly 50% discount is free money for that traffic.
Never batch a workload with real user-facing latency requirements. The discount is real, but it isn't worth it if a person is waiting on the other end; keep interactive paths synchronous.
Handle batch results per-request, not as a pass/fail unit. A large batch can have individual request failures alongside successes; retry only the failed custom_ids rather than reprocessing the entire batch.
Run the engineering break-even math before building batch infrastructure. Submission, polling, and result-retrieval logic has a fixed engineering cost; below a certain request volume, that cost exceeds what the discount saves.
Tag logged costs by processing path (sync vs batch). Blending the two into one average cost-per-request metric hides which lever is actually driving your savings.

D - Measurement and Governance

Count tokens before sending unpredictable-size requests. messages.count_tokens is free and exact for the input side; use it to gate or estimate cost before a user-supplied document or long context hits the API.
Log usage.input_tokens, output_tokens, cache_creation_input_tokens, and cache_read_input_tokens on every call. These four fields are the ground truth for reconciling actual spend against any pricing model you've built, and for catching regressions early.
Keep per-model rate tables in reviewable config, not hardcoded literals. Pricing changes on its own schedule, intro-pricing windows expire, model generations retire; a rate table baked into business logic silently drifts out of date.
Write an ADR for the team's default model tier, and name its review triggers explicitly. A documented default with clear conditions for revisiting it prevents both silent cost creep and undocumented tribal knowledge.
Treat a cheaper model's failures and rework cost as part of its real price. A low-tier model that needs frequent escalation or manual correction can cost more end to end than a stronger model that gets the task right the first time; measure total cost of correctness, not just per-token price.
Re-run cost estimates after any pricing change, not just once at launch. A cost model built at feature launch and never revisited will silently diverge from reality as rates, discounts, and model lineups evolve.

Applying These Practices in Order

Start with A (1-5): model selection is the highest-leverage, lowest-effort lever, get the default right before investing in caching or batch infrastructure.
Layer in B (6-9): prompt caching has a low break-even and applies to almost any workload with a stable system prompt or tool catalog, add it early.
Add C (10-12) once volume justifies it: batch's savings are real but the engineering cost only pays off above a certain volume; don't build it prematurely.
Keep D (13-16) running continuously: measurement and governance aren't a one-time setup, they're what keeps the other three categories honest as pricing and task mix evolve.

FAQs

Which practice should a team implement first if starting from zero?

Model selection (section A): pick an explicit default tier and document it. It's the highest-leverage, lowest-effort change and everything else builds on top of it.

Is it ever fine to skip prompt caching entirely?

Yes, if a workload genuinely has no reused prefix, every request is truly unique content, caching adds cost with no offsetting savings. Caching is a lever for reuse, not a universal default.

What's the single most common mistake in this list?

Defaulting to the strongest model "just in case" instead of matching model tier to actual task difficulty. It's the easiest mistake to make because it feels safe, and the most expensive one at scale.

How do I know if my workload has enough volume to justify a router or batch integration?

Run the break-even calculation: divide the one-time engineering cost by the per-request savings. If your expected request volume clears that number comfortably, the investment pays for itself.

Should every request be logged with full usage details?

For any production workload with real cost implications, yes, the four usage fields are cheap to log and are the only reliable way to reconcile actual spend against your cost model later.

Why does this list separate "model selection" from "measurement and governance"?

Model selection is a decision you make once (per feature or per team), while measurement and governance are ongoing practices that verify the decision still holds as conditions change. Conflating the two makes it easy to set a good default and then forget to revisit it.

Is a documented ADR really necessary, or is a config default enough?

A config default tells you what the current setting is; an ADR tells you why, under what conditions it should change, and what alternatives were rejected. Both matter, but only the ADR prevents the decision from being reverse-engineered later.

Does this best-practices list assume a specific volume or company size?

No, but the weighting of effort should scale with volume, sections A and B apply almost universally, while C and D's engineering investment should be sized to actual request volume and budget stakes.

What's the fastest way to tell if these practices are working?

Compare blended actual cost per request (from logged usage) against what a flat, unoptimized single-model policy would have cost for the same traffic. A shrinking gap over time signals the practices are paying off.

How Claude Token Pricing Actually Works - the underlying pricing model these practices are built around.
Sonnet 5 vs Opus 4.8 vs Fable 5: A Cost-Per-Task Comparison - the task-by-task data behind the model-selection practices.
Prompt Caching ROI: When Cache Writes Actually Pay Off - the break-even math behind the caching practices.
ADR Template: Choosing a Default Model Tier for Your Team - turning the model-selection practices into a documented team decision.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, pricing, and SDK versions move quickly - verify current specifics at platform.claude.com/docs before relying on them.

Token Economics Best Practices

How to Use This List

Treat section A as the baseline every new feature should start from; sections B-D are levers to apply once volume justifies the engineering cost.
Don't apply every practice to every feature, a low-volume internal tool doesn't need a router or batch integration, match the investment to the volume.
Revisit this list whenever pricing changes materially, especially around known transition points like Sonnet 5's 2026-08-31 intro-pricing expiration.
Pair the model-tier practices with a written ADR so the default isn't just a convention nobody remembers agreeing to.

A - Model Selection

Default new features to Sonnet 5, not the strongest model. Sonnet 5 handles the large majority of everyday tasks well, and reaching for Opus 4.8 or Fable 5 "just in case" bakes in a 2.5x to 5x cost multiplier for capability most tasks don't need.
Reserve Opus 4.8 and Fable 5 for genuinely hard reasoning tasks. Multi-step reasoning under ambiguity, high-stakes trade-off analysis, and safety-critical judgment calls are where the premium tiers earn their cost; templated or pattern-matching work rarely is.
Route high-volume, low-complexity tasks to Haiku 4.5. Classification, extraction, and simple formatting tasks run well on the cheapest tier, and the savings compound fastest exactly where volume is highest.
Build a router once volume justifies it, not before. A classifier that sends SIMPLE tasks to Haiku and HARD tasks to Opus pays for its own engineering cost only above a certain volume threshold; below that, a flat default is the more efficient use of engineering time.
Never let model choice default to "whatever was used in testing." An explicit, documented default (see the ADR template) prevents cost decisions from being made by accident.

B - Prompt Caching

Cache any prefix reused more than once within its TTL window. The arithmetic break-even for prompt caching is low, often just the second reuse, so err toward caching stable, repeated content rather than skipping it.
Put the most stable content first, most volatile content last. Claude assembles the cached prefix in a fixed order (tools, then system, then messages); structuring content this way maximizes what a breakpoint can cover.
Never interpolate per-user or per-session data into a cached block. A username, timestamp, or session ID inside the cached prefix invalidates the cache on every single call, silently erasing the savings.
Choose TTL based on real request spacing, not habit. Bursty, closely-spaced traffic favors the cheaper 5-minute TTL; traffic with gaps regularly exceeding 5 minutes favors the pricier 1-hour TTL despite its higher write cost.
Build cached content from one shared constant, not scattered inline literals. Even semantically identical text can fail to match byte-for-byte if it's rebuilt inconsistently across call sites, which silently breaks cache hits.
Monitor cache_read_input_tokens vs cache_creation_input_tokens in production. The theoretical break-even calculation only matters if real traffic is actually clearing it; log both fields and watch the ratio over time.

C - Batch Processing

Route any latency-tolerant, high-volume workload through the Batch API. Nightly reports, bulk classification, and offline dataset processing rarely need a synchronous response, and the roughly 50% discount is free money for that traffic.
Never batch a workload with real user-facing latency requirements. The discount is real, but it isn't worth it if a person is waiting on the other end; keep interactive paths synchronous.
Handle batch results per-request, not as a pass/fail unit. A large batch can have individual request failures alongside successes; retry only the failed custom_ids rather than reprocessing the entire batch.
Run the engineering break-even math before building batch infrastructure. Submission, polling, and result-retrieval logic has a fixed engineering cost; below a certain request volume, that cost exceeds what the discount saves.
Tag logged costs by processing path (sync vs batch). Blending the two into one average cost-per-request metric hides which lever is actually driving your savings.

D - Measurement and Governance

Count tokens before sending unpredictable-size requests. messages.count_tokens is free and exact for the input side; use it to gate or estimate cost before a user-supplied document or long context hits the API.
Log usage.input_tokens, output_tokens, cache_creation_input_tokens, and cache_read_input_tokens on every call. These four fields are the ground truth for reconciling actual spend against any pricing model you've built, and for catching regressions early.
Keep per-model rate tables in reviewable config, not hardcoded literals. Pricing changes on its own schedule, intro-pricing windows expire, model generations retire; a rate table baked into business logic silently drifts out of date.
Write an ADR for the team's default model tier, and name its review triggers explicitly. A documented default with clear conditions for revisiting it prevents both silent cost creep and undocumented tribal knowledge.
Treat a cheaper model's failures and rework cost as part of its real price. A low-tier model that needs frequent escalation or manual correction can cost more end to end than a stronger model that gets the task right the first time; measure total cost of correctness, not just per-token price.
Re-run cost estimates after any pricing change, not just once at launch. A cost model built at feature launch and never revisited will silently diverge from reality as rates, discounts, and model lineups evolve.

Applying These Practices in Order

Start with A (1-5): model selection is the highest-leverage, lowest-effort lever, get the default right before investing in caching or batch infrastructure.
Layer in B (6-9): prompt caching has a low break-even and applies to almost any workload with a stable system prompt or tool catalog, add it early.
Add C (10-12) once volume justifies it: batch's savings are real but the engineering cost only pays off above a certain volume; don't build it prematurely.
Keep D (13-16) running continuously: measurement and governance aren't a one-time setup, they're what keeps the other three categories honest as pricing and task mix evolve.

FAQs

Which practice should a team implement first if starting from zero?

Model selection (section A): pick an explicit default tier and document it. It's the highest-leverage, lowest-effort change and everything else builds on top of it.

Is it ever fine to skip prompt caching entirely?

Yes, if a workload genuinely has no reused prefix, every request is truly unique content, caching adds cost with no offsetting savings. Caching is a lever for reuse, not a universal default.

What's the single most common mistake in this list?

Defaulting to the strongest model "just in case" instead of matching model tier to actual task difficulty. It's the easiest mistake to make because it feels safe, and the most expensive one at scale.

How do I know if my workload has enough volume to justify a router or batch integration?

Run the break-even calculation: divide the one-time engineering cost by the per-request savings. If your expected request volume clears that number comfortably, the investment pays for itself.

Should every request be logged with full usage details?

For any production workload with real cost implications, yes, the four usage fields are cheap to log and are the only reliable way to reconcile actual spend against your cost model later.

Why does this list separate "model selection" from "measurement and governance"?

Is a documented ADR really necessary, or is a config default enough?

Does this best-practices list assume a specific volume or company size?

No, but the weighting of effort should scale with volume, sections A and B apply almost universally, while C and D's engineering investment should be sized to actual request volume and budget stakes.

What's the fastest way to tell if these practices are working?

How Claude Token Pricing Actually Works - the underlying pricing model these practices are built around.
Sonnet 5 vs Opus 4.8 vs Fable 5: A Cost-Per-Task Comparison - the task-by-task data behind the model-selection practices.
Prompt Caching ROI: When Cache Writes Actually Pay Off - the break-even math behind the caching practices.
ADR Template: Choosing a Default Model Tier for Your Team - turning the model-selection practices into a documented team decision.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5 - and the official anthropic Python SDK (latest 0.x release). Model names, pricing, and SDK versions move quickly - verify current specifics at platform.claude.com/docs before relying on them.

Token Economics Best Practices

Search Documentation

Token Economics Best Practices