Prompt caching (improve cache hit rate)

In multi-turn conversations, with long system prompts, or when you send the same document again and again, most of each request's input is identical to the previous one. With prompt caching enabled, that repeated content is served from cache: cached input tokens are billed at the vendor's cache-read list price, and time to first token usually drops too.

This page applies to models that support prompt caching, called through POST /v1/messages (Claude-native format). Pick a model on the model square that supports /v1/messages and use its model ID.

Basics: mark content blocks with cache_controlCopy Anchor Link

Replace your-model-id in the samples with a model ID from the model square (or call GET /v1/models).

Add "cache_control": {"type": "ephemeral"} to the content block you want cached. Caching works on the prefix: everything from the start of the request up to that marker (tools → system → messages) is cached, and the next request with an identical prefix hits the cache.

The most common pattern is to write a long system prompt as an array of content blocks and mark the last one:

curl https://ai.myaiexp.com/v1/messages \
  -H "x-api-key: $MYAIEXP_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "You are an AI assistant tasked with analyzing literary works. <long reference material here>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Analyze the major themes in Pride and Prejudice."
      }
    ]
  }'

In multi-turn conversations, you can also add a cache_control to the last content block of the last message, so the history keeps hitting the cache as the conversation grows.

Cache lifetime: 5 minutes by default, 1 hour optionalCopy Anchor Link

The default cache lifetime is 5 minutes, refreshed on every hit. If the gap between requests is often longer than 5 minutes (for example, a user replies every ten-odd minutes), request a 1-hour cache explicitly:

{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }

When requests are already frequent (gaps under 5 minutes), the 5-minute cache is refreshed continuously and never expires, so a 1-hour cache only adds write cost. Cache write and read prices per model are on the model square, synced daily from each vendor's official public list price.

When testing hit rate: there is a minimum token countCopy Anchor Link

The cached prefix must reach the model's minimum length, or nothing is cached. There is no error; cache_creation_input_tokens and cache_read_input_tokens are simply both 0. So don't test with a one- or two-sentence prompt; use a long system prompt or document.

The minimum cacheable length differs between models, and newer models don't necessarily have a smaller minimum. See Anthropic's documentation for the exact values. If both cache fields stay at 0, make the prefix longer and test again.

How to confirm a hitCopy Anchor Link

Check the usage field of the response. Send the same request twice; the second response looks like this (numbers are illustrative):

"usage": {
  "input_tokens": 12,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 2051,
  "output_tokens": 380
}

Total input tokens = input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Usage and charges for each request are also shown in the console's Usage Logs.

Tips for a higher hit rateCopy Anchor Link

• Put fixed content first and changing content last. The cache matches on prefix in the order tools → system → messages; a change to any earlier byte invalidates everything after it.
• Don't put timestamps, request IDs or other per-request values in the system prompt. This is the most common reason for a 0% hit rate.
• Keep tool lists and JSON stable. Tool order and field order should be the same on every request.
• In multi-turn conversations, put the breakpoint on the latest message. The breakpoint moves forward with the conversation and the history keeps hitting the cache.
• A request can have at most 4 cache breakpoints. Place them on tools, system and messages to cache content that changes at different rates in layers.
• Use /v1/messages. cache_control is a parameter of the Anthropic Messages format; when you need precise control over caching, use the approach on this page rather than Chat Completions.