Thinking and prompt caching

Prompt caching interacts with thinking in a few specific ways. The following rules apply in both thinking modes.

Configuration changes invalidate caching. The thinking configuration and the resolved effort level are rendered into the prompt itself, so changing any of them starts a new cache prefix. Switching between adaptive, enabled, and disabled, changing budget_tokens, and changing the effort value all invalidate cache breakpoints: message-level breakpoints always miss, and tool and system-prompt breakpoints can miss too, depending on where the model renders the configuration. Treat any thinking or top-level effort change as starting the cache over. On models that support per-message effort, an effort change carried in a role: "system" message inside messages leaves the cached prefix intact. Consecutive requests that keep the same configuration preserve the cache, and setting a parameter explicitly to its default value is equivalent to omitting it. A thinking block the API drops under either preserved-thinking condition changes the cached prefix from that block's position onward. Blocks passed back unchanged keep the cache intact. A worked demonstration with usage output is on the Steering thinking page.

Thinking blocks are cached with tool results. During a tool-use loop, caching occurs when you make a follow-up request that includes tool results. At that point the previous conversation history, including its thinking blocks, can be cached, and those cached thinking blocks count as input tokens in your usage metrics when read from the cache. This occurs automatically, even without explicit cache_control markers, and behaves the same for regular and interleaved thinking. The tradeoff: thinking blocks you never see again in responses still contribute to input token usage when read from cache.

Whether prior blocks are in context at all is per-model. The preservation default governs this. On keep-all models, previous turns' thinking blocks stay cached and in context. On last-turn-only models, once you send a user message that isn't a tool result, all previous thinking blocks are stripped from context. On those models, a conversation like this:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

is processed as if the thinking blocks were never there:

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

On keep-all models, the same request keeps thinking_block_1 and thinking_block_2 in context and in the cache.

Degradation strips thinking from the cacheable history. If thinking becomes disabled mid-turn and you pass thinking content in the current tool-use turn, the thinking content is stripped and thinking remains disabled for that request (see graceful degradation). Interleaved thinking amplifies cache invalidation effects, because thinking blocks can occur between multiple tool calls.

Thinking-heavy tasks often take longer than the default 5-minute cache lifetime to complete. Consider the 1-hour cache duration to maintain cache hits across longer thinking sessions and multistep workflows.