Claude Opus 5’s new prompt-caching API slashes token bills for chat-style apps by letting the model skip re-reading unchanged text. The first request pays a modest premium; every subsequent hit costs roughly one-tenth of the base rate, turning a recurring expense into a one-time charge.

Why developers pay twice for the same words

Most conversational interfaces rebuild the full prompt on every turn: an 8,000-token system prompt, attached PDFs, and the full dialogue history travel together to the model each time a user asks a follow-up. The model re-processes every token even though the bulk of that text never changes. At current pricing, that redundancy can dominate the cost of a busy bot.

How the cache changes the math

The API creates a cache entry for every “block” of tokens up to a defined breakpoint. When the next request contains the same block at the front, the service reads it from cache instead of tokenising it again. The pricing split reflects the work saved:

  • Cache write – 5-minute TTL: 1.25 × base price
  • Cache write – 1-hour TTL: 2 × base price
  • Cache read (hit): 0.1 × base price

In practice, the first call to a new block costs a little more than a normal request. Every later call that hits the cache is 90 % cheaper, so the net spend drops sharply as the conversation deepens.

The “golden rule” for structuring prompts

Cache effectiveness hinges on where you place static versus dynamic content. Put everything that stays the same at the front, and push the ever-changing pieces to the end. A reliable ordering looks like this:

  1. Tools – definitions of any external functions the model may call.
  2. System instructions – the high-level behavior you want the model to follow.
  3. Documents – long context such as PDFs, knowledge bases, or policy excerpts.
  4. User questions – the live query that varies every turn.

If you modify any token before a breakpoint, the cache entry is invalidated and the model must re-process everything that follows.

Hidden limits you need to respect

  • Minimum block size – Opus 5 only caches blocks that contain at least 512 tokens. Anything smaller falls through the cache entirely.
  • Timestamp bug – inserting a changing timestamp inside a cached block guarantees a miss, because the block’s text never matches exactly.
  • 20-block look-back – the service scans only the last 20 blocks for a match. Long-running sessions that jump ahead quickly can outrun the cache window.
  • Parallel requests – firing several identical requests at the same instant will all miss, because the cache is populated only after the first request finishes. Warm the cache with a single call, then issue the rest.

Seeing the savings in your API response

Each response reports three token counters:

  • cache_read_input_tokens – tokens that came from a cache hit.
  • cache_creation_input_tokens – tokens written to the cache in this request.
  • input_tokens – the new tokens that were not cached.

Add the three numbers together to get the total tokens the model considered for that turn. If both cache fields are zero, the request missed the cache; check your block size and breakpoint placement.

Takeaway: By front-loading immutable context and letting Claude Opus 5’s prompt-caching API do the heavy lifting, you turn a recurring token expense into a one-off charge. The result is a dramatic cost reduction for any chatbot that repeatedly references the same system prompt or document set—provided you respect the token floor, avoid mutable markers inside cached blocks, and keep your cache-eligible content within the 20-block horizon.