What prompt caching does
The API lets you mark a point in your prompt as a cache breakpoint. On subsequent requests within a TTL (five minutes by default, one hour available), everything up to that breakpoint is read from cache. Cache reads cost roughly a tenth of fresh input tokens. Cache writes cost a bit more than fresh input tokens — but you only pay that once.
The layout that works
Structure prompts so stable content comes first and volatile content comes last:
[ system instructions — stable ]
[ tool definitions — stable ]
[ shared context, docs, schema — stable ]
<CACHE BREAKPOINT>
[ conversation history — changes every turn ]
[ current user message — always new ]
The breakpoint is placed at the boundary between "this will be identical next request" and "this might change." Everything before is cached.
The code
const response = await client.messages.create({
model: 'claude-opus-4-7',
max_tokens: 2048,
system: [
{
type: 'text',
text: systemInstructions,
cache_control: { type: 'ephemeral' }, // breakpoint here
},
],
messages: conversationHistory,
});
The cache_control marker on a block means "cache up to and including this block." You can have up to four breakpoints.
Multiple breakpoints for agents
For agents that accumulate turns, mark breakpoints at stable boundaries:
messages: [
...oldTurns, // stable by the time we send turn N
{ ...lastAssistantTurn, cache_control: { type: 'ephemeral' } },
currentUserTurn,
]
After turn N+1, the first N turns are all cached. You only pay fresh-input rates for the new user turn and the assistant's new output.
What actually happened with our numbers
Before caching: ~$0.60 per agent turn, dominated by the 40k system prompt + growing history.
After caching with one breakpoint after the system prompt: ~$0.15 per turn. Cache write costs on the first request of a session, but subsequent requests within five minutes paid only for the variable tail.
After adding breakpoints at conversation-history boundaries: ~$0.12 per turn for long sessions.
75% reduction. No change in output quality because the cached content is byte-identical.
TTL is the design constraint
Five-minute TTL means your session cadence matters. A user who sends a message every minute stays cached. A user who sends one every seven minutes pays cache-write costs again. The one-hour TTL option helps for slower workflows but costs more to write.
For chat, five minutes is usually fine. For batch agents that fire every few minutes, five minutes works. For agents that might sit idle for 20 minutes, either use the one-hour TTL or plan for the cache miss.
The most common mistake
Putting the cache breakpoint after volatile content. Even one changed byte before the breakpoint invalidates the whole cache. Keep volatile content — user messages, dates, request IDs — strictly after the breakpoint.
Once the layout is right, caching is almost free money. It was the single highest-ROI change we made to our AI bill this year.