Gemini API Context Caching: Cost Controls

Gemini context caching cuts the cost of sending the same large prompt repeatedly, but only when you cache stable material, set a sensible expiry and measure the saving.

The pattern

Every Gemini API call is billed on the tokens you send. If your product sends the same 80-page manual or the same long system instruction with every request, you pay for those tokens every time. Context caching stores that shared prefix on Google's side once, and subsequent requests that reference it are billed at a reduced rate for the cached tokens.

There are two forms at the time of writing:

• Implicit caching is on by default for Gemini 2.5 and newer models. You do nothing; if a request shares a long enough prefix with a recent one, you may get a cache hit. You can see hits in the response's usage metadata. It is a bonus, not a guarantee.
• Explicit caching is where you create a cache object with a model, the content, an optional system instruction and a time to live. Requests then reference the cache by name. Google describes the saving as guaranteed. The Interactions API supports implicit caching only.

Minimum sizes apply. At the time of writing the documented minimum is 2,048 tokens for Gemini 2.5 Flash and 2.5 Pro and 4,096 tokens for the Gemini 3.x models. Below that, nothing is cached.

Explicit caching is billed on two things: the number of cached tokens at the reduced rate, and storage, charged per million tokens per hour for the life of the cache. Normal input and output tokens on each request are charged as usual. Caching is not available on the free tier.

A worked example

A UK distributor builds an internal assistant that answers staff questions about a 100,000-token product and returns manual using Gemini 2.5 Flash. Staff ask around 200 questions a day during an eight-hour working day.

At the time of writing the published paid-tier prices for 2.5 Flash are 0.30 US dollars per million input tokens, 0.03 per million cached tokens and 1.00 per million tokens per hour of storage. Check the pricing page before quoting these internally; they move.

Without caching: 200 requests × 100,000 tokens = 20 million input tokens, about 6.00 US dollars a day for the manual alone.

With an explicit cache that lives for the working day: cached reads 20 million × 0.03 per million = 0.60; storage 100,000 tokens × 8 hours = 0.8 million token-hours × 1.00 = 0.80; total about 1.40 a day plus the initial upload and the small per-question tokens. The saving is roughly three quarters of the manual cost.

Now change one assumption. If the same manual is used by two staff who ask five questions a day between them, storage still costs 0.80 and the cached reads save almost nothing. Caching would cost more than it saves. The break-even is a question of request volume against hours of storage, and you should do this sum for each use case.

In code, the shape is simple. Create the cache with a TTL such as "28800s" for eight hours, or leave it unset for the default of one hour. Reference cache.name in the cached_content field of each request. Read usage_metadata.cached_content_token_count on each response to confirm the cache is being used. Use caches.update to extend the TTL, caches.list to see what exists, and caches.delete when the day is done.

Pitfalls

1. Caching material that changes. A price list that is updated at 10am means every answer until the cache expires is wrong. Cache the manual, not the stock levels. Tie cache creation to the document's version and rebuild on change.
2. Leaving caches running. A cache created with a long TTL and forgotten is a storage bill and a retention question. Delete it at the end of the process that created it and reconcile caches.list against what you expect.
3. Caching personal data. Cached content sits in Google's infrastructure until expiry. If the prefix contains customer records or staff data, you have created a new copy that your retention schedule and your data protection assessment need to know about. Prefer caching reference documents and keeping personal data in the per-request part of the prompt.
4. Assuming implicit caching will save you. It may, but you cannot budget on it. Use explicit caching where the saving matters and confirm it through the usage metadata.
5. Caching below the minimum. A 1,500-token system prompt is not cached on any current model. Do not restructure a product around a saving that will not happen.
6. Not measuring. Log cached token count and total token count per request for a week. If the ratio is low, the prefix is not shared as often as you thought.

Controls for a small team

Put the cache TTL, the rebuild trigger, the data classes allowed in cached content and the owner in the same place you record the rest of the integration's design. If the assistant can also take actions through function calling, keep the approval rules from our Gemini API function calling approval note alongside it. For the consumer and Workspace side of Gemini limits, see Gemini usage limits.

Review the pricing page each quarter. A price change in either direction can move the break-even point for a use case you have already shipped.

Source basis

• Gemini API: context caching
• Gemini API: explicit caching with generateContent
• Gemini API: pricing