Gemini's Long Context: Prompting Across a Million Tokens

TL;DR: Gemini's current flagship models handle up to 1,048,576 input tokens, real and verified, but not the 2-million-token figure some searches still expect. What's genuinely Gemini-specific: a consumer app window that's plan-gated from 32k all the way to 1M, native GitHub-repo and 1,000-page PDF ingestion, and an implicit token cache that rewards putting your biggest files first.

How big is Gemini's context window right now, and is it really 2 million tokens?

No, not on any model Google currently documents. Checking directly at Google's own model reference pages: Gemini 3.8 Flash, now listed under Google's "Stable" tier and described as "Our most intelligent Flash model, engineered for long-horizon software engineering, autonomous agents, and complex enterprise workflows." It lists an input token limit of 1,048,576 and an output limit of 65,536. Gemini 3.1 Pro Preview, still under Google's "Preview" heading, publishes the identical pair of numbers. Neither page, nor Google's long-context guide, nor its context-caching guide, mentions a 2-million-token figure anywhere.

If you've seen "2M" attached to Gemini, that's a stale number circulating from an earlier generation. Treat any Gemini context claim bigger than 1,048,576 as unverified until you find it on a live ai.google.dev page yourself.

The more interesting number is what happens in the consumer app, because it isn't fixed at all. It's gated by subscription tier in a way the API simply isn't:

That's a 32x spread between the free tier and the top tier, on the same product. A prompt that works perfectly on a Pro or Ultra account can silently lose track of earlier content on a free one, for no reason related to your prompt at all.

That gap has one more wrinkle worth knowing if you're inside AI Ultra specifically. Deep Think, the plan's maximum-reasoning mode, trades window size for depth rather than adding to it: Google's own plan documentation states "Deep think (AI Ultra only) provides maximum parallel reasoning" and, separately, that "Deep think requires the Pro model." Its own window caps at 192k tokens even on the tier that otherwise unlocks the full million, a reminder that the biggest plan and the biggest window aren't always the same setting.

What does a million tokens actually look like in practice?

Bigger than most people picture, and Google puts real numbers on the analogy rather than leaving it abstract. Its own long-context guide frames it this way: 1 million tokens looks roughly like 50,000 lines of code, all the text messages you've sent in the last five years, 8 average-length English novels, or transcripts of more than 200 average-length podcast episodes.

Google's own flagship example of what that capacity enables in practice is a genuinely striking one: "using only in-context instructional materials (a 500-page reference grammar, a dictionary, and ≈400 parallel sentences), Gemini learned to translate from English to Kalamang—a Papuan language with fewer than 200 speakers—with quality similar to a human learner using the same materials." No fine-tuning, no training run. The entire "lesson" lived inside a single prompt's context window. That's in-context learning at a scale most other tools can't attempt, and it's the specific capability that makes whole-codebase and whole-book workflows viable rather than theoretical.

Both current flagship-class models publish the identical 1,048,576/65,536 pair, so choosing between Gemini 3.8 Flash and Gemini 3.1 Pro Preview for a long-context task isn't a capacity question at all. It's a stability tradeoff: Flash carries Google's "Stable" label and is described for long-horizon agentic and coding work specifically, while Pro still sits under "Preview" despite being the more capability-forward line. For a production pipeline that processes the same repository or document set daily, that label is worth weighing on its own, separate from anything about window size.

How do you hand Gemini an entire codebase?

Directly, through a workflow that's genuinely different from pasting files one at a time. Gemini Apps lets you import a GitHub repository by URL or upload a whole local code folder, and Google's own upload-limits documentation states the ceiling plainly: "One code folder, or one GitHub repository, with up to 5,000 files and a maximum size of 100 MB, can be added to a chat." That's a materially different starting point than most competing chat interfaces, which cap you at attaching individual files.

Once the repository is in context, the retrieval discipline is the one that makes any long-context prompt trustworthy rather than a guess: ask Gemini to cite the specific file and line before it concludes anything. Our Claude long-context guide covers that same quote-before-reasoning pattern for documents; for code specifically, a workable version looks like this:

Before answering, list every file and function in the repository above that
touches authentication or session handling. Cite the file path for each one.

Only after you've listed them, answer: {{YOUR_QUESTION}}

If the codebase doesn't contain enough information to answer confidently,
say so explicitly rather than guessing from general framework knowledge.

Outside the consumer app, the same capacity is reachable through the Files API for automated workflows, and it carries its own separate, verified limits: "The Files API lets you store up to 20 GB of files per project, with a per-file maximum size of 2 GB. Files are stored for 48 hours." Build against that expiry deliberately. A pipeline that re-queries the same uploaded repository or document set on day three needs to re-upload it, not just re-reference an old file ID.

How do you hand Gemini an entire book or a stack of long documents?

Up to a real, documented ceiling, not an arbitrary one you have to discover by trial and error. Google's document-processing guide states it directly: "Gemini supports PDF files up to 50MB or 1000 pages. This limit applies to both inline data and Files API uploads. Each document page is equivalent to 258 tokens."

Do the arithmetic and the whole-book framing turns concrete rather than staying a metaphor: a maxed-out, 1,000-page PDF costs roughly 258,000 tokens, well under a quarter of the 1,048,576-token ceiling on Gemini's current flagship models. That leaves genuine room to load a second reference document, a style guide, or a running summary alongside it in the same prompt, rather than treating the page limit as the point where you have to start dropping content.

In the consumer app, the file-count ceiling matters as much as the page count: "Up to 10 files (subject to availability) can be uploaded in the same prompt." Sizing per file is capped too: "Each video can be up to 2 GB. All other supported file types can be up to 100 MB." A genuinely book-length project usually means fewer, larger files rather than many small ones.

Does Gemini's own placement guidance agree with itself across images, documents, and video?

Not entirely, and this is worth knowing before you copy one placement rule across every media type you send it. On the general long-context question, where to put a large block of text relative to your question, Gemini agrees with Claude and both vendors' own documentation says to supply the bulk of your material first and put your specific question at the end (our Claude long-context guide covers that shared rule, Anthropic's own published improvement from it, and where OpenAI parts ways with both).

But Google's own per-modality guides give a different, more specific instruction depending on what single item you're attaching alongside your text, and the three don't point the same direction:

Image wants the prompt first; document and video both want it last. None of the three guides cross-references the others, so there's no acknowledgment anywhere in Google's own docs that the image guidance points the opposite direction from the other two. If you're building a template that attaches a single image, a single scanned page, and a single video clip through the same code path, don't assume one placement rule covers all three. Check which media type you're actually sending.

How does context caching change the economics of a long-context prompt?

Substantially, and it happens automatically rather than requiring you to opt in. Google's caching documentation is direct: "Implicit caching is enabled by default for all Gemini 2.5 and newer models." Google is explicit that this needs no configuration on your end: "We automatically pass on cost savings if your request hits caches. There is nothing you need to do in order to enable this."

The minimum token count needed to even qualify for a cache hit differs by model generation:

Google's own advice for raising your odds of a hit is exactly the structural habit long-context prompting already rewards for accuracy reasons: "Try putting large and common contents at the beginning of your prompt" and "Try to send requests with similar prefix in a short amount of time". Put the shared, reused material first for two independent reasons at once. Gemini follows it more reliably, and it's cheaper the next time you send something similar.

The saving is real money, not a rounding error. Google's own long-context guide states that cached input and output "is ~4x less than the standard input / output cost" per request on Gemini Flash, a meaningful number if your product is a chat-with-your-documents workflow where the same uploaded files get queried repeatedly.

Does throwing more tokens at Gemini always help, or does it just cost more and run slower?

Not always, and Google's own FAQ on this is refreshingly direct rather than marketing-hedged. On whether padding a prompt with tokens you don't strictly need hurts anything: "Generally, if you don't need tokens to be passed to the model, it is best to avoid passing them. However, if you have a large chunk of tokens with some information and want to ask questions about that information, the model is highly capable of extracting that information (up to 99% accuracy in many cases)."

That accuracy number comes with a cost dimension attached, and it's a genuinely useful piece of arithmetic if you're building a retrieval-heavy product rather than answering one-off questions. Google states it plainly: "You can get ~99% on a single query, but you have to pay the input token cost every time you send that query. So for 100 pieces of information to be retrieved, if you needed 99% performance, you would likely need to send 100 requests." That's exactly the multi-needle problem the callout below names, quantified: high accuracy per query, at the cost of one full context payment per query, unless caching absorbs the repeat.

Latency scales with size too, though Google is careful not to overstate it: "There is some fixed amount of latency in any given request, regardless of the size, but generally longer queries will have higher latency (time to first token)." A single 900,000-token prompt will feel slower to start responding than a 5,000-token one, even before either request's actual reasoning work begins.

A copy-paste template for a real long-context task on Gemini

Put the pieces from this guide together and you get one reusable shape: the bulk material goes first, for both retrieval accuracy and cache-hit odds, a cite-before-conclude instruction sits in the middle, and the actual question goes last.

{{PASTE YOUR LARGEST, MOST-REUSED CONTENT HERE — repo, PDFs, transcripts}}

Step 1: Quote or cite the specific passages, files, or timestamps above that
are directly relevant to the question below. Do not paraphrase in this step.

Step 2: Based only on what you just cited, answer:
{{YOUR_QUESTION}}

If the material above doesn't contain enough to answer fully, say so
explicitly rather than filling the gap from general knowledge.

If your actual workflow is closer to a live voice conversation than a single large upload, that's a different surface with different limits. See our guide to prompting Gemini Live and voice mode. And if the material you're feeding Gemini is mixed media rather than one long document, our multi-modal Gemini prompting guide covers image, video, and audio input together in more depth than the placement quirks above. Whichever surface you're on, the throughline of this whole guide is the same: Gemini's window is genuinely large by any current vendor's standard, but the number on the model card only tells you the ceiling. What you put first, what you cache, and what you ask it to cite before it answers are the parts that actually determine whether that ceiling gets used well or wasted.