Gemini model deprecation: dates, replacements and a migration checklist

wpnews.pro

Gemini 2.5 retired on Vertex AI on October 20, 2026. Which Gemini models are deprecated, what replaces them, and a six-step migration checklist.

Google retired gemini-2.5-pro, gemini-2.5-flash and gemini-2.5-flash-lite on Vertex AI (now documented as Gemini Enterprise Agent Platform) on October 20, 2026, and requests to those model IDs through Vertex no longer work. On the Gemini Developer API, the one you reach with an AI Studio key, the same three models have no shutdown date, but Google now serves them only to projects that already used them. The next hard dates are November 17, 2026, when several Gemini API Live and TTS previews shut down, and November 19, 2026, when gemini-3.6-flash retires on Vertex. For almost every retired text model, Google's listed replacement is gemini-3.8-flash, or gemini-3.5-flash-lite where cost matters more than capability.

The migration checklist, short version:

+Inventory every Gemini model ID your code, configs and eval harness call, and note which surface each call goes through: Vertex or the Gemini API.
+Look up each date on that surface's page. The two surfaces publish different dates for the same model ID.
+Pick a pinned replacement , not a-latest alias, and check that it is not itself on a short clock.
+Update the request.thinking_budget becomesthinking_level ,temperature is ignored, a few parameters now return errors, and function-calling history is stricter.
+Replay real production traffic on the old and new model, and diff tool calls, JSON fields and refusals, not just whether the answers read well.
+Cut over per route with a rollback path , and put the replacement's own retirement date on the calendar.

The rest of this post is the detail behind each step, with the dates as of October 26, 2026. They come from Google's Gemini API deprecations page ↗ and the Vertex model versions page ↗. Check both before you act on any row, because Google updates them often.

## Which Gemini models are deprecated right now #

Model ID	Gemini API (AI Studio key)	Vertex AI / Agent Platform	Listed replacement
`gemini-2.5-pro`	No shutdown date. Existing users only	Retired October 20, 2026	`gemini-3.8-flash` or`gemini-3.5-flash`
`gemini-2.5-flash`	No shutdown date. Existing users only	Retired October 20, 2026	`gemini-3.8-flash` or`gemini-3.5-flash-lite`
`gemini-2.5-flash-lite`	No shutdown date. Existing users only	Retired October 20, 2026	`gemini-3.8-flash` ,`gemini-3.5-flash-lite` or Gemma 4
`gemini-2.0-flash` ,`gemini-2.0-flash-lite`	Shut down June 1, 2026	Retired June 1, 2026	Differs by surface, see below
`gemini-3-pro-preview`	Shut down March 9, 2026	—	`gemini-3.1-pro-preview`
`gemini-3.5-flash`	Not shutting down. Requests are routed to `gemini-3.6-flash`	Available until at least May 19, 2027	—
`gemini-3.6-flash`	No shutdown date announced	Retires November 19, 2026	`gemini-3.8-flash`
`gemini-3.7-flash`	Not shutting down. Requests are routed to `gemini-3.8-flash`	Retires January 28, 2027	`gemini-3.8-flash`
`gemini-3.1-flash-lite`	Earliest shutdown May 7, 2027	Available until at least May 7, 2027	`gemini-3.5-flash-lite`
`text-embedding-004`	Shut down January 14, 2026	—	`gemini-embedding-2`
`gemini-embedding-001`	Earliest shutdown May 14, 2028	—	`gemini-embedding-2`

A dash means the page for that surface lists nothing. For the 2.0 models the two pages disagree: the Gemini API lists gemini-3.6-flash for gemini-2.0-flash and gemini-3.1-flash-lite for gemini-2.0-flash-lite, while Vertex lists gemini-3.5-flash-lite for both. Voice and audio models have their own deadline. On the Gemini API, gemini-3.1-flash-live-preview, gemini-2.5-flash-native-audio-preview-12-2025, gemini-2.5-flash-preview-tts, gemini-2.5-pro-preview-tts and gemini-3.1-flash-tts-preview all shut down on November 17, 2026, in favor of gemini-3.8-live and the gemini-3.8-flash-tts models. On Vertex, gemini-live-2.5-flash-native-audio retires on December 13, 2026.

If you need a Pro-class model rather than a Flash one, note that Vertex lists only Flash models as the replacement for 2.5 Pro. The Pro-class options are gemini-3.1-pro-preview, which is still a preview, and gemini-4-argon, the flagship released October 13, 2026, which comes with its own migration notes: it does not support explicit caching, and Google asks for HTTP timeouts of at least 20 minutes per call.

## Why the same model has two retirement dates #

The Gemini API and Vertex are separate products with separate lifecycle policies, and the October 20 retirement only applied to Vertex. Which one your code hits depends on how the client is built, not on the model string. With the google-genai SDK, a client created with vertexai=True (or through the environment variables that select Vertex, such as GOOGLE_GENAI_USE_VERTEXAI, plus a project and location) runs on Vertex. A client created with an API key runs on the Gemini API.

The two policies also promise different things:

+Vertex splits models into two tables. Models in the first are available for at least 12 months after release. Models with a shorter availability period, likegemini-3.6-flash andgemini-3.7-flash , stay up until a replacement ships and Google posts a fixed retirement date at least 45 days out. Vertex dates can be extended but are never moved earlier.
+The Gemini API lists the earliest date a model might be shut down and promises to communicate the exact date in advance. Once a model is shut down, its endpoint is gone.

So the practical rule is that the date that applies to you is the one on the page for the surface your client talks to. Teams that run the API in development and Vertex in production can have one environment working and the other failing on the same model ID.

## The deprecations that don't fail: auto-routing and -latest aliases #

A shutdown is loud. Your calls fail and someone gets paged. Two kinds of change on the Gemini API are quiet:

+Auto-routing. The Gemini API sends requests forgemini-3.5-flash togemini-3.6-flash , and requests forgemini-3.7-flash togemini-3.8-flash . If you call either ID, you have already migrated, without a test run and without a diff.
+-latest aliases. An ID likegemini-flash-latest is hot-swapped with every new release of that model. Google promises two weeks' email notice for breaking changes, and nothing for the rest.

Both are the same failure in different clothes: the model behind your feature changed and the config file did not. You can at least see it happen, because every response says which model answered. Log it next to each call:

from google import genai

client = genai.Client()
resp = client.models.generate_content(model="gemini-3.7-flash", contents="ping")
print(resp.model_version)  # the model that actually served the request

An alert on a change in model_version per route catches a swap the day it happens, instead of when a downstream count drifts.

## Step 1: inventory every Gemini model ID and the surface it runs on #

Model strings hide in more places than the application code: environment files, Terraform, prompt registries, notebooks, batch jobs, and the eval harness itself, where judge and embedding models are easy to forget. Start with a grep and read every hit:

grep -rhoE "(gemini|text-embedding)-[a-z0-9.-]*[0-9][a-z0-9.-]*|gemini-[a-z-]*latest" \
  --exclude-dir={node_modules,.git,.venv,dist} . | sort | uniq -c | sort -rn

For each ID, write down three things: the surface (Vertex or Gemini API), the route or feature that calls it, and what it does there: tool calling, JSON output, free text, embeddings or audio. That last column decides how much testing step 5 needs.

Two kinds of model need more than a string change. Embedding models are one: vectors from different embedding models are not comparable, so moving from gemini-embedding-001 to gemini-embedding-2 means re-embedding your whole index and re-checking retrieval quality, not just changing the query-side call. Tuned models are the other. If you fine-tuned a 2.5 model on Vertex, check what the replacement supports before you plan around it. A forum thread from August 2026 points out that Vertex documents batch inference as unsupported for tuned Gemini 3 and higher models.

## Step 2: look up each date on the page for that surface #

Put each ID from step 1 against the deprecations page for its surface: the Gemini API page ↗ for API keys, the Vertex page ↗ for Vertex clients. Sort by date. Anything already past its date is an outage or an unplanned migration you have already shipped. Anything inside 45 days is this sprint.

## Step 3: choose a pinned replacement, not an alias #

Use the replacement Google lists, as a pinned ID, and check its own row before you commit to it. The obvious trap right now: on the Gemini API, gemini-2.0-flash lists gemini-3.6-flash as its replacement, and on Vertex gemini-3.6-flash retires on November 19, 2026. Migrating onto a model with a short clock means doing this twice. gemini-3.8-flash is listed on Vertex as available until at least September 2, 2027, and it is the ID most of the table above points to.

A -latest alias looks like a way out of the deprecation treadmill. It is the opposite: it swaps the model under you with every release, and you lose the before-and-after comparison that makes a migration safe.

## Step 4: update the request for Gemini 3.8 Flash #

Google's developer guide to Gemini 3.8 Flash ↗ lists what changes in the request. Coming from 2.5, these are the lines that matter:

In your 2.5-era request	On `gemini-3.8-flash`	What to do
`temperature` ,`top_p` ,`top_k`	Ignored by the backend. No error	Remove them, and stop relying on `temperature=0` for repeatable output. See step 5
`thinking_budget` (an integer)	Replaced by `thinking_level` :`LOW` ,`MEDIUM` (the default) or`HIGH`	Map each budget to a level. The lowest is `LOW` , so a 2.5 Flash call with`thinking_budget=0` cannot keep thinking off
`thinking_level: MINIMAL`	API validation error	Use `LOW`
`candidate_count` ,`frequency_penalty` ,`presence_penalty`	API error	Remove them
A prefilled model turn, or history ending on a `model` turn	Unsupported	Remove it. Use structured output to force a format
A `FunctionResponse` that doesn't echo its call	Must match the `id` ,`name` and execution count of the preceding`FunctionCall`	Pass back the call's `id` and`name` on every response
Rebuilding chat history from stored text	Gemini 3 models expect thought signatures back in multi-turn and function-calling history	Send history back as the API returned it, signatures included

The ignored temperature is the dangerous row, because nothing fails. Code that set temperature=0 to make a classifier repeatable keeps running on 3.8 Flash and is no longer repeatable. If you target a Gemini 3 Pro-class model instead, Google's advice runs the other way: keep temperature at its default of 1.0, because lower values can cause looping or degraded output. PDF and video inputs also change token counts under Gemini 3's media_resolution settings, so check the cost of any document-heavy route.

## Step 5: replay production traffic on both models and diff the behavior #

Everything up to here makes the new model answer. This step finds out whether it still does the same job. A model swap is a behavior change, and the regressions that matter mostly read fine: a tool argument changes format, an enum field moves one notch, a request the old model refused turns into a tool call. Reading a few outputs in AI Studio will not show you any of that.

The method, in brief:

+Build the cases from production logs , not from prompts you make up: 100 to 300 real inputs, stratified by route, with what production actually did (tool calls, arguments, JSON fields) stored as the expectation.
+Assert deterministically first. Check the tools called, the argument formats, and field equality on every enum. Use an LLM judge only for free text, and treat its results as advisory.
+Take several samples per case on 3.8 Flash. Withtemperature ignored, one sample cannot tell a regression from sampling noise. Score the fraction of samples that pass.
+Compare per route, never one average. A 5% drop on one route disappears in the overall number.

There is one timing problem specific to this deprecation. If you are on Vertex, 2.5 is already gone, so the only baseline you have is what you logged before October 20. If you are on the Gemini API and your project still has 2.5 access, record a baseline run now, while the old model still answers. The same applies to gemini-3.6-flash on Vertex before November 19.

The full walkthrough of this step, with code and the six regressions it caught on a real model upgrade, is in How to catch LLM regressions before a model upgrade ships.

## Step 6: cut over with a rollback path #

Switch one route at a time, behind a flag, starting with the route the diff in step 5 cleared most clearly. Where the old model still answers (Gemini API projects with 2.5 access, Vertex gemini-3.6-flash until November 19), keep it as the fallback until the new route has run for a week. Watch error rates, latency, cost and model_version per route. Then add the replacement's own retirement date to the team calendar, with a reminder 45 days ahead, because this checklist will run again.

## Doing this with EvalShift #

Disclosure: I'm the founder of EvalShift, and step 5 is the part it automates. The capture SDK wraps the google-genai client and records real runs, including tool calls and the generation config, and compare replays them against the candidate model:

from google import genai
from evalshift import capture
from evalshift.adapters.genai import wrap_genai

client = wrap_genai(genai.Client())  # records each call inside a capture session

TOOLS = [...]  # the function declarations the agent is offered, or [] for none

@capture.agent(suite="support", redact=True, tools=TOOLS)  # no-op unless EVALSHIFT_CAPTURE=1
def handle_ticket(message): ...
pip install evalshift
EVALSHIFT_CAPTURE=1 python my_agent.py   # record production-shaped runs
evalshift capture sync                   # recorded runs -> golden suite
evalshift compare --suite-name support --to gemini-3.8-flash

Both arms are live calls, so run it while the old model still answers. When it no longer does, the tool evaluators can still score the candidate against the trace production recorded (against: expected). For the ignored temperature, set defaults.samples_per_example above 1 so each case is sampled several times. The verdict comes from a migration_policy written before the run, and the report shows the per-example diff. Docs: /docs/sdk-adapters, /docs/evaluators, /docs/migration-policy.

## FAQ #

Is Gemini 2.5 Flash deprecated? On Vertex AI, yes: gemini-2.5-flash, gemini-2.5-pro and gemini-2.5-flash-lite retired on October 20, 2026. On the Gemini Developer API they are not deprecated and have no shutdown date, but Google limits access to projects that have already used them and recommends gemini-3.8-flash or gemini-3.5-flash-lite for new work.

What happens when a Gemini model is shut down? The endpoint is turned off and requests to that model ID fail. Google documents no automatic redirect for the retired 2.5 models on Vertex. The exceptions are gemini-3.5-flash and gemini-3.7-flash on the Gemini API, which keep working by routing requests to gemini-3.6-flash and gemini-3.8-flash.

How much notice does Google give before retiring a Gemini model? On Vertex, models in the standard table are available for at least 12 months after release. Shorter-lived models get a fixed retirement date at least 45 days ahead, and dates are never moved earlier. On the Gemini API, listed dates are the earliest possible shutdown, and -latest aliases get two weeks' email notice before a breaking swap.

What should replace Gemini 2.5 Pro? Vertex lists gemini-3.8-flash or gemini-3.5-flash. If you need Pro-class reasoning, the options are gemini-3.1-pro-preview, which is still a preview, or the flagship gemini-4-argon. Replay real traffic on whichever you pick: a Flash model replacing a Pro one is the swap most likely to change behavior on hard cases.

Should I use gemini-flash-latest to avoid future deprecations? No. A -latest alias is hot-swapped with every new release, so it trades one planned migration for many untested ones. Pin a version and run the migration checklist when its date comes.

## Keep reading #

+How to catch LLM regressions before a model upgrade ships — step 5 in full, with code and the six failures it caught.
+What actually breaks when you switch LLMs — why the worst regressions from a model swap read as correct.
+Build a golden eval suite from production traffic — capturing the baseline before the old model is gone.
+Evaluating agent tool calls — what to check when the agent's trace matters more than its text.

source & further reading

evalshift.dev — original article How to catch LLM regressions before a model upgrade ships This one passed: 71% cheaper, and the agent still does the same thing What breaks when you switch LLMs?