Gemini 2.5 Deprecation: A Pre-Cutover Checklist Before Requests Auto-Route on December 1

The Gemini 2.5 deprecation takes effect on December 1, 2026. On that date, calls to gemini-2.5-pro and gemini-2.5-flash start routing automatically to different models. Most requests will keep succeeding, which is exactly why you should look now.

This guide covers what Google announced, the bill impact, the parameters that need rewriting, and how to decide per workload whether to accept the reroute or pin a model deliberately. If you run Gemini on Vertex AI, read that section first. Its retirement date has already passed.

What Google Announced and What Actually Changes on December 1

Google's Gemini API release notes, published on November 2, 2026, say that calls to gemini-2.5-pro will route automatically to gemini-3.8-flash, and calls to gemini-2.5-flash will route to gemini-3.5-flash-lite. The release notes set December 1, 2026 as the date the routing begins. From that date, any API request that still names either model will be answered by a different, newer model and charged at that model's prices.

The scope is narrower than the headline implies. The Gemini deprecations page says gemini-2.5-flash-lite is not deprecated and remains available until further notice. Only two model IDs are affected.

The practical problem is that nothing usually returns an error. A different model quietly answering may go unnoticed.

Why a Silent Reroute Is Riskier Than an Error

From Google's side, rerouting is a sensible default because teams that miss the notice stay online. It also means output quality, latency, token usage and cost can change even though nobody on the customer side touched any code.

The maintainers of the open-source llm-exe library raised this in a GitHub issue: calls keep succeeding, but gemini-2.5-pro users get a Flash-tier model with no warning. They call this a real capability downgrade and say it is "worse than a 404 because nobody will notice."

Google has left some questions open. Its notice does not explain why 2.5 Pro maps to a Flash model rather than a higher tier, and it does not say whether customers can opt out of the automatic routing.

We suggest treating the cutover as a model change your team did not choose, and reviewing it like a planned upgrade, with an evaluation pass, a cost check and an owner's sign-off.

The Cost Picture: Cheaper in December, Different From January 2027

Google's launch post for Gemini 3.8 Flash gives an introductory price of $0.75 per 1M input tokens and $3.75 per 1M output tokens through December 31, 2026. Gemini 2.5 Pro costs $1.25 and $10.00 on prompts up to 200,000 tokens. From January 1, 2027, the 3.8 Flash rates double to $1.50 and $7.50. At those rates input costs more than it did on 2.5 Pro, though output stays cheaper.

Two illustrative workloads

A third-party analysis from Data Studios works through two example workloads. They are not benchmarks and not Optijara measurements.

In the support-assistant example, the monthly bill drops from $9,300 to $4,500 in December and then climbs back to $9,000 from January 2027. The token volumes behind those totals are in the Data Studios analysis, so check them there before comparing with your own traffic.

The long-document row lists its assumptions, so you can recompute it from the price table. It comes to $810 on 2.5 Pro because each prompt lands in the pricier long-context band. On 3.8 Flash it costs $240 in December and $480 from January, because 3.8 Flash has no long-context surcharge.

Token counts matter more than token prices

Google's launch post says 3.8 Flash might use more tokens to maximize performance, especially at higher effort levels. Higher volume can eat some or all of a lower per-token price. Measure real token counts on your own traffic before trusting any spreadsheet, the examples above included.

Parameter Changes That Break or Silently Change Behavior

thinking_budget becomes thinking_level

Gemini 3.x models use thinking_level instead of thinking_budget. Gemini 3.8 Flash accepts the levels low, medium and high, and Google's 3.8 Flash model documentation says minimal returns an error. Confirm the current wording in the Gemini API changelog and the model page.

This is one of the few places a rerouted request can fail outright, so check any code, config or wrapper that sets or maps to minimal. We suggest also testing how a leftover thinking_budget value behaves on a rerouted request.

Sampling parameters are on the way out

Google's migration guidance tells developers to remove temperature, top_p and top_k. These parameters are deprecated, are ignored today and will return HTTP 400 in future generations. Remove candidate_count too, since Gemini 3 and later do not support it. Check the Gemini API changelog and the deprecations page before touching code.

This is not only a reroute issue. Google's Gemini API docs confirm that these sampling parameters are ignored on Gemini 3.6 Flash, Gemini 3.5 Flash-Lite and Gemini 3.5 Flash Cyber. If you call those models, some of your settings may already be doing nothing. A workflow that relied on low temperature for consistent output has lost that control, so test consistency directly.

The 2.5 Flash to 3.5 Flash-Lite path

We suggest separating what is documented on this path from what your team still needs to test or look up.

• Known: output limits. Gemini 3.5 Flash-Lite, the replacement for 2.5 Flash, has a 1M-token context window and supports up to 64,000 output tokens. Check that your max output settings and chunking logic fit.
• Known: sampling parameters. Already ignored on 3.5 Flash-Lite, as noted above.
• To test: thinking levels. We suggest testing every thinking_level value you plan to send, minimal included.
• To look up: cost. We suggest pricing this path from Google's current published rates.

Tool and function calling

Tool calling needs its own test pass. We suggest re-testing every tool-calling flow end to end against the target model, covering tool selection, argument formatting, multi-turn state and error handling. Teams may find it safer to treat earlier behavior as unverified until those tests pass.

Playbook: A Seven-Step Gemini 2.5 Migration Checklist

We suggest giving each step an owner and a target date ahead of the cutover.

• [ ] Step 1, inventory. Search code, config, environment variables, infrastructure templates and SDK wrappers for gemini-2.5-pro and gemini-2.5-flash, including defaults inside third-party libraries and agent frameworks. Exclude gemini-2.5-flash-lite.
• [ ] Step 2, classify. Tag each call by business risk (customer-facing, reasoning-heavy, tool-calling, batch, long-context) and assign an owner.
• [ ] Step 3, rewrite parameters. Replace thinking_budget with thinking_level (low, medium or high; no minimal on 3.8 Flash). Test each level on 3.5 Flash-Lite. Remove temperature, top_p, top_k and candidate_count.
• [ ] Step 4, re-test. Run a fixed evaluation set and your tool-calling flows against the target model, comparing quality, latency and token usage with a baseline from the current model.
• [ ] Step 5, cost model. Price measured token usage per path.
• [ ] 2.5 Pro workloads: at 3.8 Flash December 2026 rates, then at January 2027 rates.
• [ ] Former Flash workloads: we suggest pricing these from Google's current published rates for the target model.
• [ ] Step 6, decide. Pin each workload to an explicit model ID, or write down that you accept the reroute target.
• [ ] Step 7, monitor after December 1. Log the requested model ID and any model or version metadata the response returns, and alert when they differ. The requested ID alone won't reveal a reroute. Track tokens and spend, and watch caching, since Google has not documented how responses or caches behave under rerouting.

For Step 7, per-request traces that record requested model, reported model, token counts and latency make drift visible fast. Teams may find our OpenTelemetry GenAI tracing playbook a useful starting point for this kind of tracing.

Pin on Purpose or Accept the Reroute: The Three-Dial Review

We call our framework for this decision the Three-Dial Review. Score each workload low, medium or high on each dial.

• Risk. Who sees the output, and what happens when it's wrong? Customer-facing answers, regulated content and tool calls that change data score high.
• Reasoning dependence. Did you pick 2.5 Pro for multi-step reasoning, or did it just become the default?
• Cost sensitivity. How much of your Gemini spend does this workload drive, and how fast is it growing?

If risk or reasoning dependence is high, we suggest testing first and pinning explicitly to whichever model passes. If both are low and cost sensitivity is high, accepting the reroute target is reasonable, but pin it explicitly anyway. Mixed scores go to evaluation, with January pricing as a tiebreaker. Long-context workloads deserve a close look, since the illustrative example above still shows savings after the January change.

Google's launch post also says that where compute efficiency is the main constraint, developers can use lower effort levels or keep using Gemini 3.7 Flash, which remains fully supported for efficiency-first workloads. If efficiency is your main constraint, we suggest including that model in your evaluation as a pinning option.

Google reports a 54.9% score for 3.8 Flash on HLE-Verified. That's vendor-reported context, not proof the model fits your task. We suggest letting your own evaluation set decide, and our piece on why benchmark scores need protocols offers further reading on how to weigh headline numbers.

We suggest pinning explicitly even when you choose the model the reroute would have picked. Teams may find that a pin turns a vendor default into a documented decision they can revisit as pricing changes. If traffic passes through a gateway, consider enforcing explicit model pins at the gateway layer so a stray default in one service can't bypass it.

Vertex AI: The Retirement Date Has Already Passed

The Vertex lifecycle table lists October 20, 2026 as the retirement date for both gemini-2.5-pro and gemini-2.5-flash. That date is behind us. Vertex AI calls that still name either model may already be failing or being served by another model, so check this week's logs and error rates for those IDs before turning to the Developer API.

Vertex AI documents model lifecycles separately from the Gemini Developer API. Google says that when it schedules a model for retirement there, it posts a fixed date that gives you at least 45 days to migrate. The suggested replacements differ too: gemini-3.8-flash or gemini-3.5-flash for Pro, and gemini-3.8-flash or gemini-3.5-flash-lite for Flash. Google's rerouting notice does not say how the December 1 change applies to Vertex AI. If you use both surfaces, check each on its own terms.

Common Mistakes Teams Make With This Migration

• Capturing the baseline too late. After December 1, a Gemini API call to gemini-2.5-pro no longer reaches 2.5 Pro.
• Missing defaults in CI and test fixtures. We suggest checking fixtures, mocks, smoke tests and staging configs for hard-coded model IDs.
• Leaving caches and evals keyed to old IDs. Teams may find that anything keyed on the model string mixes older and rerouted results under one label. Re-key it, or mark the cutover date.
• Tuning budget alerts during December. Thresholds set on December spend will understate January, when 3.8 Flash rates double.
• Migrating the wrong calls, or missing hidden ones. gemini-2.5-flash-lite is not deprecated, and affected IDs can hide inside third-party wrappers your repository search won't find.

Caveats and Open Questions

Google has not said whether responses will show that a rerouted request was served by the replacement model. It also hasn't said what happens to explicit context caches created on Gemini 2.5 models, and there is no stated opt-out.

The cost scenarios here come from a third-party analysis using illustrative workloads. Your traffic mix, prompt lengths and effort settings will produce different numbers. Benchmark figures are vendor-reported. Pricing and documentation can change, so we suggest rechecking the official changelog and deprecations pages before acting.

If a second pair of eyes would help, Optijara can run a migration audit of your Gemini calls or help build the eval baseline you'll compare against.