Skip to Content
ModelsClaudePrompt caching

Claude prompt caching

This page explains how to enable prompt caching for Claude and confirm cache hits. For model IDs and endpoints, see the Claude family overview.

Key pointClaude caching requires an explicit cache_control marker; neither endpoint caches automatically.

Put long, fixed content (system prompts, documents, tool definitions) at the start of the request, and set cache_control on the last fixed content block. Subsequent requests whose prefix is exactly identical will hit the cache.

claude_cache.py
import os
import anthropic
 
client = anthropic.Anthropic(base_url="https://api.ofox.ai/anthropic", api_key=os.environ["OFOX_API_KEY"])
LONG_DOC = open("manual.txt", encoding="utf-8").read()  # a long, fixed document
 
for question in ["What does chapter 3 cover?", "Summarize the key points of the whole document."]:
    message = client.messages.create(
        model="anthropic/claude-sonnet-4.6",
        max_tokens=1024,
        system=[
            {"type": "text", "text": "Answer questions based on the document below."},
            {"type": "text", "text": LONG_DOC, "cache_control": {"type": "ephemeral"}},
        ],
        messages=[{"role": "user", "content": question}],
    )
    u = message.usage
    print("Write:", u.cache_creation_input_tokens, "Read:", u.cache_read_input_tokens)
ItemDetails
TTL5 minutes by default, reset on each hit; "cache_control": {"type": "ephemeral", "ttl": "1h"} sets 1 hour
Confirming hits (native API)On the first request usage.cache_creation_input_tokens is greater than 0; on a hit usage.cache_read_input_tokens is greater than 0
Confirming hits (OpenAI-compatible API)On a hit usage.prompt_tokens_details.cached_tokens is greater than 0
Minimum lengthContent that is too short is not cached, and both fields are 0. For each model’s minimum cacheable length, see the Anthropic docs 
BillingWrites and reads are billed at the cache write and cache read rates respectively — see the model page 

For general information on caching, see Prompt caching.

For other errors, see Common errors.

Last updated on
Extended thinkingWeb search