Docs

Prompt caching

How to cache the fixed part of your prompt and cut the bill noticeably.

If your app sends the same long system prompt every time, you are paying full price for that fixed text on every call. Prompt caching is exactly the fix.

How it is billed

Token kind	Rate
Normal input	The base input rate
Cache write	Slightly above normal input
Cache read	Far below normal input

Exact rates are on each model's page. If a model has no separate cache rate its page says so explicitly — that means caching buys nothing there, not that it is free.

The requirement: keep the prefix identical

Caching works only when the start of the prompt repeats byte for byte. One small difference at the front voids the whole cache.

python

messages = [
    # fixed — always identical, always first
    {"role": "system", "content": LONG_INSTRUCTIONS},
    # variable — after the fixed part
    {"role": "user", "content": user_question},
]

Always put the fixed part first.
Never put the current time, a random ID or the user's name inside the fixed part — those belong in the user message.

To confirm caching is actually engaging, check the token columns in Usage. If nothing changed after this edit, your prefix still differs per call.