Gemini Context Caching: Implicit vs Explicit, Pricing, Hit Rates

Gemini context caching comes in two forms, and which one you get depends on the model and the API you call. Implicit caching is automatic on Gemini 2.5 and newer: when a request starts with the same long prefix as a recent one, the repeated tokens are billed at the cached rate and you configure nothing. Explicit caching lets you store content as a cachedContents object and point later requests at it for a guaranteed discount, but only on Gemini 3-series models such as 3.8 Flash, 3.6 Flash and 3.1 Pro Preview, plus 2.5, and only through the generateContent API. Gemini 4 Argon has implicit caching only, and the Interactions API has no explicit caching on any model. That is Google's documentation as of October 30, 2026.

What you change depends on the model. On gemini-4-argon, remove any caches.create call or cached_content setting, put the static system prompt or document at the very start of the request, and read cachedContentTokenCount in each response to see what was cached; cached input costs $0.10 per 1M tokens through November 30, 2026 and $0.20 from December 1. On gemini-3.8-flash and the other models with explicit caching, an explicit cache costs $0.50 per 1M tokens per hour to store, and its creation is billed at the full input price; a cache you keep for one hour still beats resending the tokens from the second request in that hour, so it is the safer choice for a document or codebase you query several times an hour.

Don't build a budget on implicit caching alone. In test calls through a third-party gateway on October 30, 2026, 3.8 Flash requests sharing a prefix of 5,605 tokens or more hit the cache on 13 of 40 tries, nothing hit below 5,000 tokens even though Google lists a 4,096-token minimum, and no hit covered the whole prompt. A real hit cut the input cost by 44–78%, not the 90–95% on the price page.

Which Gemini models get implicit or explicit caching

Every current Gemini model in the Gemini API gets implicit caching, but explicit caching stops at Gemini 4 Argon. Google's Gemini API context caching guide for generateContent describes implicit caching as on by default with "no cost saving guarantee", and explicit caching as available on Gemini 3 and 2.5 models with a "cost saving guarantee", in Beta under v1beta, and "not supported for Gemini 4 Argon and onward".

The API surface matters as much as the model. The Gemini API context caching guide for the Interactions API says that API "only supports implicit caching", in both stateful (previous_interaction_id) and stateless mode, and tells you to switch to generateContent if you want explicit caches on a supported model. Google's docs now file generateContent under "Generate Content API (Legacy)", so if you are starting new code on the Interactions API, plan on implicit caching only.

Moving to Argon is where most code breaks. Google's Gemini 4 Argon migration notes say explicit caching "is not supported on Gemini 4 Argon and returns an error", and ask you to remove calls that create or pass cached_content. On Google Cloud's Gemini Enterprise Agent Platform (formerly Vertex AI) the split is the same: Argon is absent from the explicit caching model list in the Agent Platform context caching overview. Explicit caching isn't the only Argon change that throws errors; another common one is covered in Gemini "Requests ending with a model turn are not supported" Fix.

If you are coming from Claude, the model is different: Claude caches what you mark with cache breakpoints and charges extra to write the cache, explained in Claude Prompt Caching: How It Works, Costs, 512-Token Minimum.

Gemini context caching pricing: what a hit saves and when storage pays

On the Gemini API pricing page (Standard paid tier, per 1M tokens, as of October 30, 2026), cached input costs 5% of the input price on Gemini 4 Argon and 10% on the other models. Explicit caches add a storage charge per hour, so the useful number is how often you must reuse a cache before that storage is cheaper than resending the tokens: storage per hour ÷ (input price − cached price).

The last two columns answer different questions. The long-lived figure, storage ÷ (input − cached), ignores the one-time creation charge, so it fits a cache you keep for many hours: for 3.8 Flash it is $0.50 ÷ ($0.75 − $0.075) = 0.74 reads an hour, and it stays 0.74 in 2027 because the input, cached and storage prices all double on January 1. A cache you create and keep for a single hour also pays its creation at the full input price, so it needs (input + storage) ÷ (input − cached) requests in that hour to beat sending the tokens uncached: ($0.75 + $0.50) ÷ $0.675 = 1.85 on 3.8 Flash, which means 2 or more requests. Argon has no storage charge to recover, so every hit is pure saving, and the saving per hit doubles on December 1 along with the price.

The creation charge comes from Google Cloud's caching overview, which says the input tokens used to create a cache are billed at the standard input price, for implicit and explicit caching alike, so the first request always pays full price. Here is what that means for one hour of a 100,000-token document on 3.8 Flash at 2026 prices, counting the document's input tokens only:

The explicit column is $0.075 to create the cache, plus $0.0075 per request to read 100,000 cached tokens, plus $0.05 of storage for the hour; the "1 in 4" column rounds the number of hits down. The comparison with implicit caching follows from it. At 10 requests an hour, implicit caching only beats the $0.20 explicit cost if all nine repeats hit in full, because eight full hits already cost $0.75 − 8 × $0.0675 = $0.21. At the roughly one-in-three hit rate in the test below, the explicit cache is already cheaper at 3 requests an hour ($0.1475 versus about $0.18 expected for implicit). So implicit caching wins only when nearly every repeat hits and covers the whole document, which the measured hits below never did.

The full per-model rate card, Batch and Flex rates and the Prepay rules are in Gemini API Pricing 2026: Token Rates, Free Tier, and Key Cost. How OpenAI and Anthropic bill cached tokens and cache writes, for comparison, is in OpenAI vs Claude Cache Pricing: How Cached Tokens, Cache Writes, and Cache Reads Are Billed.

Create, use, extend and delete an explicit cache in Python

An explicit cache takes four calls in the google-genai Python SDK: caches.create to store the shared content, generate_content with cached_content to reuse it, caches.update to extend it, and caches.delete to stop paying for storage. This follows the pattern in Google's generateContent caching guide and works only on models with explicit caching, such as gemini-3.8-flash; on gemini-4-argon the create call fails.

import datetime
import os
import pathlib

from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
MODEL = "gemini-3.8-flash"

manual = pathlib.Path("product_manual.txt").read_text(encoding="utf-8")

# 1. Store the static part once: instructions plus the long document
cache = client.caches.create(
    model=MODEL,
    config=types.CreateCachedContentConfig(
        display_name="product-manual-v1",
        system_instruction="Answer support questions using only the manual.",
        contents=[manual],
        ttl="3600s",  # 1 hour; the default if you leave it out
    ),
)
print(cache.name, cache.usage_metadata)

# 2. Each request sends only the new question and points at the cache
response = client.models.generate_content(
    model=MODEL,
    contents="How do I reset the device to factory settings?",
    config=types.GenerateContentConfig(cached_content=cache.name),
)
print(response.text)
print(response.usage_metadata.cached_content_token_count)

# 3. Extend the cache while traffic continues (time must be timezone-aware)
client.caches.update(
    name=cache.name,
    config=types.UpdateCachedContentConfig(
        expire_time=datetime.datetime.now(datetime.timezone.utc)
        + datetime.timedelta(hours=2)
    ),
)

# 4. Delete it when you are done instead of waiting for the TTL
client.caches.delete(name=cache.name)

A few rules shape how you use this. The model treats cached content as a prefix of the prompt, so the cache holds the part that never changes and each request adds only what is new. You can change a cache's ttl or expire_time but nothing else, so a new version of the document means a new cache. caches.list() and caches.get() return metadata such as name, model, token count and expiry, but Google provides no way to read the cached content back. Storage is billed for as long as the cached tokens are stored, which is why the last step deletes the cache rather than leaving it to expire.

The same flow exists in the JavaScript and Go SDKs and over REST, where you POST to https://generativelanguage.googleapis.com/v1beta/cachedContents and pass the returned name as cachedContent in a generateContent request. If you use the OpenAI library against Google's endpoint, Google's guide says to pass cached_content through extra_body.

How to check if a Gemini request hit the cache

A hit shows up as a cached-token count in the response's usage block, and a miss shows nothing: in the October 30, 2026 test responses described further down, the key was simply absent on a miss rather than set to 0. The field name depends on the API you call.

This is a real hit from a 3.8 Flash generateContent call. promptTokenCount is the whole prompt including the cached part, so the tokens billed at the full input rate are 11,645 − 8,165 = 3,480:

"usageMetadata": {
  "promptTokenCount": 11645,
  "cachedContentTokenCount": 8165,
  "candidatesTokenCount": 56,
  "totalTokenCount": 11701,
  "cacheTokensDetails": [{ "modality": "TEXT", "tokenCount": 8165 }]
}

On the OpenAI-compatible route the same kind of hit looked like "prompt_tokens": 11644, "prompt_tokens_details": {"cached_tokens": 8161}, and a miss returned "prompt_tokens_details": {}. Because the field can be missing, log it with a default of zero so a miss doesn't crash your cost tracking:

usage = response.usage_metadata
cached = usage.cached_content_token_count or 0
full_price = usage.prompt_token_count - cached
print(f"{cached} of {usage.prompt_token_count} prompt tokens cached; {full_price} at full price")

To turn that into money, multiply the full-price tokens by the input rate and the cached tokens by the cached rate. For the hit above at 3.8 Flash list prices that is 3,480 × $0.75 + 8,165 × $0.075 per 1M tokens, or $0.003222 instead of $0.008734 uncached, a 63% saving on input.

Minimum tokens for Gemini implicit caching: 4,096 or 6,144?

Google publishes two different minimums and its own pages disagree, so treat 4,096 tokens as the floor for Gemini 3 and 4 models and expect hits only well above it. The tables on ai.google.dev list 4,096 tokens for Gemini 4 Argon, 3.8 Flash, 3.6 Flash and 3.1 Pro Preview, and 2,048 for 2.5 Flash and 2.5 Pro. Google Cloud's caching overview lists 4,096 for Gemini 3 and 4 models in general but 6,144 for 3.0 Flash Preview, 3.1 Pro Preview, 3.7 Flash and 3.8 Flash with implicit caching. For Argon, Cloud's Gemini 4 Argon developer guide says 6,144 in three places, while its Gemini 4 Argon model page says 4,096. As of October 30, 2026, all four pages still say this.

To see where hits actually start, repeated requests were sent on October 30, 2026 (15:15–15:51 UTC) through the laozhang.ai gateway's Gemini-native generateContent endpoint: one account, one shared prefix text, the long reference text in systemInstruction (in the user turn for 6 of the 11,600-token calls), 15–20 seconds apart, and every response reporting the requested modelVersion. Within a batch the requests were byte-identical, except for 3 of the 11,600-token 3.8 Flash calls and the 3 OpenAI-compatible calls, which asked different final questions after the same prefix. Batches sent in the same script run shared their opening text, so a later batch could reuse a cache an earlier one wrote. The batches with nothing earlier to reuse were 3.8 Flash at 4,971, 5,605, 6,143 and about 11,645 tokens (the systemInstruction calls) and Argon at 11,576; the 3.8 Flash 8,358-token batch, the OpenAI-compatible calls and the Argon 6,122-token batch began with text an earlier batch had already sent. These are gateway measurements, not direct calls with a Google API key:

Disclosure: laozhang.ai is our own service. Its prices are platform pricing, not an independent comparison.

Neither official number matched cleanly for 3.8 Flash. It never hit at 4,380 or 4,971 tokens (0 of 14 calls), though both are above 4,096, and it hit in the clean 5,605- and 6,143-token batches, the first of which is below 6,144. The Argon results don't settle Argon's minimum: the 6,122-token requests were the first 6,122 tokens of the 11,576-token batch, whose cache reached 9,522 tokens, so they show that a shorter request can be served from a cache a longer one wrote, not that a 6,122-token prompt creates a cache on its own. The practical rule: keep the shared prefix comfortably above 6,144 tokens if you want implicit hits on 3.8 Flash or Argon, and if your static content is only 4,000–5,000 tokens, don't count on implicit caching at all. A test like this is cheap to repeat on your own key and prompt: the roughly 60 calls behind this table cost $0.44 at Google list prices.

Why Gemini implicit caching is not working: what to check

Implicit caching usually "doesn't work" for one of a handful of independent reasons, and several can apply at once. Start with the response field from the previous section, then work through these:

Dynamic content at the start of the prompt is the cause you control most, and frameworks add it without telling you. A Reddit thread in r/n8n titled "Google Gemini's Implicit Context Caching" describes no cache hits in n8n and suspects the AI Agent node injects dynamic instructions at the start of the prompt. If you use an agent framework or a wrapper such as LangChain, log the exact request body it sends and check whether the first few thousand tokens are identical between calls.

Intermittent and partial hits are normal, not a bug in your code. In the October 30 test, the 6,143-token batch went miss, miss, hit, miss, miss, hit, hit, hit on byte-identical requests, and moving the long text from systemInstruction into the user turn made no clear difference at 11,600 tokens (2 of 6 hits versus 1 of 6). No hit covered the whole prompt: 2,042–4,281 tokens stayed at full price each time, always more than the short question at the end. Google gives no rule for how much of a single request gets cached. For Argon multi-turn and agent loops, it documents one: Gemini caches the full previous request only if the new request adds at least 2,050 tokens, and otherwise re-processes the last 2,050 tokens of the previous request at the standard input rate.

Hit rates also vary a lot by workload. In Artificial Analysis's Intelligence Index v5.0 runs, published October 27–28, 2026, 34% of Gemini 3.8 Flash's input tokens hit the cache versus 92% of Gemini 4 Argon's, a gap that changes which model is cheaper per task in Gemini 4 Argon vs 3.8 Flash: Cost per Task and When to Switch. If your own hit rate stays low after fixing the prompt order and you are on a model with explicit caching, an explicit cache is the only way to get a guaranteed discount.

How long a Gemini cache lasts: TTL for explicit and implicit caches

An explicit cache lives for the TTL you set, 1 hour by default, and you can extend it at any time; an implicit cache has no setting, and Google only says how long a prefix can survive at most. On the Gemini API, Google's guide says there are "no minimum or maximum bounds on the TTL", while Google Cloud's caching overview gives a 1-minute minimum and no maximum. You can change only ttl or a timezone-aware expire_time, as in the update step of the Python example.

For implicit caching, ai.google.dev publishes no lifetime and only advises sending requests with a similar prefix "in a short amount of time". Google Cloud says an implicitly cached prefix expires no later than 24 hours after it is created and that most entries are evicted earlier, and Cloud's Argon guide talks about getting the discount when requests run back-to-back within a "15–20 minute cache TTL". The October 30 test calls ran 15–20 seconds apart and still missed often, so a short gap is necessary but not sufficient.

What Gemini durable caching is, and where it applies

Durable caching is a second storage tier for implicit caching that Google documents only for Google Cloud's Gemini Enterprise Agent Platform, not for the Gemini API you call with an AI Studio key. When a cached prefix is evicted from memory, it moves to durable storage instead of being discarded, so a request that comes back later can still hit; this is aimed at workloads that reuse the same context over longer intervals. It is on by default for Gemini 4 Argon, 4 Argon Cyber Permissive, 3.8 Flash and 3.8 Flash Cyber, it has no storage charge, and a prefix still expires no later than 24 hours after creation.

Durable caching keeps derived cache data at rest, so it matters for data-retention reviews. Google's Agent Platform zero data retention page says that data is scoped to your project, stays in the selected location on regional and multi-regional endpoints (the global endpoint can use any region), is deleted within 24 hours, is never used for training, and doesn't support customer-managed encryption keys. A project's cacheConfig reports "retentionType": "DURABLE" when it is on; you can switch to in-memory only (EPHEMERAL) or set "disableCache": true to turn off all implicit caching. Google's caching overview adds that explicit caches can trigger additional implicit caching, so avoiding retention means disabling implicit caching and not creating explicit caches. If you are still choosing between the two Google routes, Gemini API vs Vertex AI API: Which Google Gemini Route Should You Use? compares them.

Does Gemini caching work through a gateway or OpenAI-compatible API?

Through the laozhang.ai gateway on October 30, 2026, implicit caching worked and explicit caching didn't. Implicit hits appeared on both the Gemini-native generateContent endpoint and the OpenAI-compatible /v1/chat/completions endpoint, where 1 of 3 calls with an 11,644-token prompt reported 8,161 cached tokens. Every explicit cache call, POST /v1beta/cachedContents for 3.8 Flash and Argon and GET /v1beta/cachedContents, returned HTTP 404 with the gateway's own Invalid URL error, so the request never reached Google. If you need explicit caches, call Google directly with a Gemini API key or an Agent Platform project.

Disclosure: laozhang.ai is our own service. Its prices are platform pricing, not an independent comparison.

Two other things change when a gateway sits in the middle. Google Cloud isolates cached data by project number and never shares it across projects, so if a gateway spreads your traffic over several upstream projects or keys, repeats may land where your prefix isn't cached; the test data can't separate that effect from Google's own "no guarantee" behavior. Pricing also follows the gateway's table rather than Google's: as of October 30, 2026, laozhang.ai lists a cache-read price of $0.075 per 1M tokens for gemini-3.8-flash but none for gemini-4-argon, so its pages don't show whether an Argon hit is billed at a discount there.

Gemini context caching: other questions

Do cached tokens count toward Gemini API rate limits?

Yes. Google's caching guide says there are no special rate or usage limits for context caching: the standard generateContent rate limits apply, and token limits include cached tokens. A cache lowers what a request costs, not how much of your tokens-per-minute quota it uses. Per-tier limits are in Gemini API Rate Limits 2026: Free vs Paid Tiers and How to Raise.

Is context caching free on the Gemini API free tier?

On Gemini 3.8 Flash, yes: as of October 30, 2026, the pricing page lists context caching as "Free of charge" on the free tier, where input is free too. Gemini 3.5 Flash-Lite lists caching as "Not available" on the free tier, and Gemini 4 Argon has no free tier at all. Which models and limits the free tier covers is in Gemini API Free Tier 2026: Limits, Free Models, and Free API Keys.

Does Batch mode stack with caching on Gemini 4 Argon?

Yes, at a lower cached rate. Google's pricing page lists Argon's Batch cached input at $0.05 per 1M tokens through November 30, 2026 and $0.10 from December 1, against Batch input of $1.00 and then $2.00, with implicit caching only, as of October 30, 2026.

Can I see what is stored in a Gemini explicit cache?

No. Google's caching guide says cached content can't be retrieved or viewed; caches.list() and caches.get() return only metadata such as the name, model, display name, token count and create, update and expire times. Keep your own copy of whatever you cached so you can rebuild the cache when it expires.