Anthropic Prompt Caching Deep Dive: Breakpoints, TTL, and Cost Optimization

1. Core Mechanism

1.1 cache_control Object

Anthropic's Prompt Caching is controlled via a cache_control object with two fields:

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}

type : Currently only supports ephemeral (temporary cache).

ttl : Two tiers: 5m (default) — 5-minute expiry, suited for high-frequency continuous requests. 1h — 1-hour expiry, suited for longer intervals where reuse is still possible.

1.2 Two Usage Patterns

Automatic caching : Place a single cache_control at the request top level; the system automatically adds a breakpoint at the last cacheable block. Example:

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  },
  "system": [
    {
      "type": "text",
      "text": "Very long system prompt..."
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Question"
    }
  ]
}

This minimal approach suits standard multi-turn conversations.

Explicit breakpoint caching : Attach cache_control to specific blocks to precisely control cache boundaries. Example:

{
  "system": [
    {
      "type": "text",
      "text": "Global stable policy...",
      "cache_control": { "type": "ephemeral", "ttl": "1h" }
    },
    {
      "type": "text",
      "text": "Business context...",
      "cache_control": { "type": "ephemeral", "ttl": "5m" }
    }
  ]
}

Both patterns can be mixed, but automatic caching consumes one of the four breakpoint quotas.

1.3 Prefix Hierarchy

Prompt Caching operates on continuous prefixes, not discrete blocks. The official concatenation hierarchy is: tools -> system -> messages Any change in an earlier layer invalidates all downstream caches. For example, modifying a tool definition invalidates both system and message caches.

2. Breakpoint Mechanism

2.1 Writes Only at Breakpoints

When a block is marked with cache_control, the system writes a single prefix hash entry up to that block. It does not automatically create independent cache entries for each preceding block. Stable content before a breakpoint is not cached unless a breakpoint was explicitly placed at its boundary.

2.2 20-Block Lookback Window

On read, the system first checks the current breakpoint for a hit. On a miss, it walks backward block-by-block, searching for previously written prefix entries. This lookback is capped at 20 positions (including the breakpoint itself).

2.3 Maximum 4 Breakpoints Per Request

Each request may contain at most four cache breakpoints. Multiple breakpoints enable layering by change frequency: when one layer changes, only that layer and subsequent layers are invalidated, not the entire prefix.

3. TTL and Billing Rules

3.1 Price Multipliers

Cache read : 0.1x

5m cache write : 1.25x

1h cache write : 2x

Cache writes cost more than normal input because the system must store cache state. The core strategy: write once, read many times, letting read savings cover the write cost.

3.2 Mixed TTL Ordering Constraint

If both 1h and 5m TTLs are used, the long TTL (1h) must appear before all short TTL (5m) breakpoints.

3.3 Cache Reads Refresh TTL

A cache hit refreshes the entry's expiry. For 5m caches, this refresh incurs no additional write cost, allowing high-frequency read scenarios to keep the cache alive indefinitely without repeated writes.

4. Observability and Evaluation

4.1 Three Key Usage Fields

The API response's usage object includes: cache_creation_input_tokens — tokens written to cache in this request. cache_read_input_tokens — tokens read from cache in this request. input_tokens — tokens not involved in cache read/write.

Relationship:

total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

4.2 Derived Metrics

Three practical metrics:

cache_read_ratio = cache_read_input_tokens / total_input_tokens

Higher is better, indicating high reuse.

write_to_read_ratio = cache_creation_input_tokens / max(cache_read_input_tokens, 1)

Persistently high values signal misplaced breakpoints or poor strategy (writing without reading).

effective_input_cost_ratio = (input_tokens
  + 0.1 × cache_read_input_tokens
  + 1.25 × cache_creation_input_tokens_5m
  + 2.0 × cache_creation_input_tokens_1h)
  / total_input_tokens

If this ratio consistently exceeds the baseline strategy, roll back or reposition breakpoints because costs have increased.

5. Spring AI Wrapper

5.1 Core Wrapper Classes

AnthropicCacheStrategy — Defines caching strategy semantics. Values: NONE, SYSTEM_ONLY, TOOLS_ONLY, SYSTEM_AND_TOOLS, CONVERSATION_HISTORY.

AnthropicCacheOptions — Cache configuration object. Default strategy=NONE, default TTL=FIVE_MINUTES, default min length=1.

CacheEligibilityResolver — Decides if current message can receive a breakpoint. Checks strategy, message type, content length, breakpoint quota.

CacheBreakpointTracker — Request-level breakpoint counter. Max 4; excess breakpoints are ignored with a warning.

AnthropicChatModel.createRequest — Materializes strategy into actual request. Injects cache_control at system/user/toolResult/toolDefinition positions.

Usage example:

var cacheOptions = AnthropicCacheOptions.builder()
  .strategy(AnthropicCacheStrategy.CONVERSATION_HISTORY)
  .multiBlockSystemCaching(true)
  .cacheToolResults(true)
  .messageTypeTtl(MessageType.SYSTEM, AnthropicCacheTtl.ONE_HOUR)
  .messageTypeTtl(MessageType.TOOL, AnthropicCacheTtl.FIVE_MINUTES)
  .messageTypeMinContentLength(MessageType.TOOL, 1000)
  .contentLengthFunction(text -> text == null ? 0 : text.length())
  .build();

5.2 Breakpoint Logic in AnthropicChatModel.createRequest()

System breakpoint

Caching off: all system texts concatenated directly. multiBlockSystemCaching=true and multiple system blocks: each system block is independent; breakpoint placed on the second-to-last block.

Otherwise: system merged into single block; breakpoint placed on that block.

User breakpoint

Scan for last user message index lastUserIndex.

Only that last user message is considered as breakpoint candidate.

Content length evaluated via combineEligibleMessagesText(...) concatenating from first non-system message to last user message.

If eligible, breakpoint placed on the last user's text block.

Tool result breakpoint

Enabled only when cacheToolResults=true.

Attempted only on the last tool message.

Breakpoint placed on the last ToolResultBlockParam of that message.

Tool definition breakpoint

When strategy permits, breakpoint placed on the last tool definition.

TTL sourced from MessageType.SYSTEM TTL configuration.

Breakpoint budget

Each successful breakpoint write calls cacheResolver.useCacheBlock().

After 4 breakpoints, further breakpoints are ignored and a warning is logged.

6. Summary

Prompt Caching is not a silver bullet, but in most AI systems it is a critical lever for cost and performance control . The mechanics are straightforward; the challenge lies in continuous observation and tuning.