## Gemini model deprecation: dates, replacements and a migration checklist

URL: https://www.evalshift.dev/blog/gemini-model-deprecation-migration-checklist
Published: 2026-10-26
Tag: migration
Summary: 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.

Takeaways:
- Google retired gemini-2.5-pro, gemini-2.5-flash and gemini-2.5-flash-lite on Vertex AI on October 20, 2026. On the Gemini Developer API the same models have no shutdown date but are limited to projects that already used them.
- The next Gemini deadlines 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 AI. Google's listed replacement for most retired text models is gemini-3.8-flash.
- Gemini model retirement dates differ by surface: the date that applies is the one on the Vertex AI page for Vertex clients and the one on the Gemini API deprecations page for API-key clients, even for the same model ID.
- Some Gemini model changes never fail a request: the Gemini API routes gemini-3.5-flash to gemini-3.6-flash and gemini-3.7-flash to gemini-3.8-flash, and -latest aliases are hot-swapped on every release. Log response.model_version per route to see it.
- Gemini 3.8 Flash ignores temperature, top_p and top_k without an error, replaces thinking_budget with thinking_level (LOW, MEDIUM or HIGH), rejects candidate_count and the penalty parameters, and requires each FunctionResponse to match its FunctionCall's id and name.

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:

1. **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.
2. **Look up each date on that surface's page.** The two surfaces publish different dates for the
   same model ID.
3. **Pick a pinned replacement**, not a `-latest` alias, and check that it is not itself on a
   short clock.
4. **Update the request.** `thinking_budget` becomes `thinking_level`, `temperature` is ignored,
   a few parameters now return errors, and function-calling history is stricter.
5. **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.
6. **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](https://ai.google.dev/gemini-api/docs/deprecations) and the
[Vertex model versions page](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions).
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, like `gemini-3.6-flash` and
  `gemini-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 for `gemini-3.5-flash` to `gemini-3.6-flash`, and
  requests for `gemini-3.7-flash` to `gemini-3.8-flash`. If you call either ID, you have already
  migrated, without a test run and without a diff.
- **`-latest` aliases.** An ID like `gemini-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:

```python
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:

```bash
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](https://ai.google.dev/gemini-api/docs/deprecations) for API keys, the
[Vertex page](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions)
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](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/guides/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.** With `temperature` 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](/blog/llm-regression-testing-model-upgrade).

## 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:

```python
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): ...
```

```bash
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/sdk-adapters), [/docs/evaluators](/docs/evaluators),
[/docs/migration-policy](/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](/blog/llm-regression-testing-model-upgrade)
  — step 5 in full, with code and the six failures it caught.
- [What actually breaks when you switch LLMs](/blog/what-breaks-when-you-switch-llms) — why the
  worst regressions from a model swap read as correct.
- [Build a golden eval suite from production traffic](/blog/build-a-golden-suite-from-production-traffic)
  — capturing the baseline before the old model is gone.
- [Evaluating agent tool calls](/blog/evaluating-agent-tool-calls) — what to check when the
  agent's trace matters more than its text.