Claude Cache Billing

Unlike the automatic caching in GPT/Gemini, prompt caching in Claude’s native API is explicitly declared: use cache_control to mark content blocks that should be cached. When a cache hit occurs, that part is billed at the cached rate.

Usage

Add cache_control to system or message content blocks:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<several thousand words of rules documentation or knowledge base>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [{ "role": "user", "content": "Answer according to the rules:……" }]
}

Verify a hit

In the response usage:

{
  "usage": {
    "input_tokens": 42,
    "cache_creation_input_tokens": 4810,
    "cache_read_input_tokens": 0,
    "output_tokens": 213
  }
}

• On the first call: cache_creation_input_tokens is counted toward cache creation (slightly above the standard price);
• On subsequent hits: cache_read_input_tokens is billed at the cached rate (far below the standard price);
• The cache is valid for minutes, and continued calls will automatically extend its lifetime.

Practical advice

• Place cache points after long and stable content: system prompts, tool definitions, reference docs;
• Cached content must match byte-for-byte; do not mix in variable fields such as timestamps in templates;
• Low-frequency calls (intervals longer than the cache lifetime) will not hit the cache, and repeatedly creating caches is actually more expensive— for low-frequency scenarios, simply do not add cache_control;
• When calling Claude through an OpenAI-compatible API, caching is handled automatically by the upstream and no such parameter is needed. See Cache Billing.