{"slug": "gemini-model-deprecation-dates-replacements-and-a-migration-checklist", "title": "Gemini model deprecation: dates, replacements and a migration checklist", "summary": "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, according to Google's Vertex model versions page and Gemini API deprecations page as of October 26, 2026. The same three models have no shutdown date on the Gemini Developer API but are now served only to projects that already used them, and 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. Google lists gemini-3.8-flash, or gemini-3.5-flash-lite where cost matters more than capability, as the replacement for almost every retired text model, and the migration requires switching thinking_budget to thinking_level, since temperature is now ignored and some parameters return errors.", "body_md": "[← all posts](https://www.evalshift.dev/blog)\n\n# Gemini model deprecation: dates, replacements and a migration checklist\n\nGemini 2.5 retired on Vertex AI on October 20, 2026. Which Gemini models are deprecated, what replaces them, and a six-step migration checklist.\n\nGoogle retired `gemini-2.5-pro`, `gemini-2.5-flash` and `gemini-2.5-flash-lite` on Vertex AI\n(now documented as Gemini Enterprise Agent Platform) on October 20, 2026, and requests to those\nmodel IDs through Vertex no longer work. On the Gemini Developer API, the one you reach with an AI\nStudio key, the same three models have no shutdown date, but Google now serves them only to\nprojects that already used them. The next hard dates are November 17, 2026, when several Gemini\nAPI Live and TTS previews shut down, and November 19, 2026, when `gemini-3.6-flash` retires on\nVertex. For almost every retired text model, Google's listed replacement is `gemini-3.8-flash`, or\n`gemini-3.5-flash-lite` where cost matters more than capability.\n\nThe migration checklist, short version:\n\n1. +**Inventory** every Gemini model ID your code, configs and eval harness call, and note which\nsurface each call goes through: Vertex or the Gemini API.\n2. +**Look up each date on that surface's page.** The two surfaces publish different dates for the\nsame model ID.\n3. +**Pick a pinned replacement** , not a`-latest` alias, and check that it is not itself on a\nshort clock.\n4. +**Update the request.**`thinking_budget` becomes`thinking_level` ,`temperature` is ignored,\na few parameters now return errors, and function-calling history is stricter.\n5. +**Replay real production traffic** on the old and new model, and diff tool calls, JSON fields\nand refusals, not just whether the answers read well.\n6. +**Cut over per route with a rollback path** , and put the replacement's own retirement date on\nthe calendar.\n\nThe rest of this post is the detail behind each step, with the dates as of October 26, 2026. They\ncome from Google's\n[Gemini API deprecations page ↗](https://ai.google.dev/gemini-api/docs/deprecations) and the\n[Vertex model versions page ↗](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions).\nCheck both before you act on any row, because Google updates them often.\n\n## ## Which Gemini models are deprecated right now\n\n| Model ID | Gemini API (AI Studio key) | Vertex AI / Agent Platform | Listed replacement | \n|---|---|---|---|\n| `gemini-2.5-pro` | No shutdown date. Existing users only | Retired October 20, 2026 | `gemini-3.8-flash` or`gemini-3.5-flash` | \n| `gemini-2.5-flash` | No shutdown date. Existing users only | Retired October 20, 2026 | `gemini-3.8-flash` or`gemini-3.5-flash-lite` | \n| `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 | \n| `gemini-2.0-flash` ,`gemini-2.0-flash-lite` | Shut down June 1, 2026 | Retired June 1, 2026 | Differs by surface, see below | \n| `gemini-3-pro-preview` | Shut down March 9, 2026 | — | `gemini-3.1-pro-preview` | \n| `gemini-3.5-flash` | Not shutting down. Requests are routed to `gemini-3.6-flash` | Available until at least May 19, 2027 | — | \n| `gemini-3.6-flash` | No shutdown date announced | Retires November 19, 2026 | `gemini-3.8-flash` | \n| `gemini-3.7-flash` | Not shutting down. Requests are routed to `gemini-3.8-flash` | Retires January 28, 2027 | `gemini-3.8-flash` | \n| `gemini-3.1-flash-lite` | Earliest shutdown May 7, 2027 | Available until at least May 7, 2027 | `gemini-3.5-flash-lite` | \n| `text-embedding-004` | Shut down January 14, 2026 | — | `gemini-embedding-2` | \n| `gemini-embedding-001` | Earliest shutdown May 14, 2028 | — | `gemini-embedding-2` | \n\nA dash means the page for that surface lists nothing. For the 2.0 models the two pages disagree:\nthe Gemini API lists `gemini-3.6-flash` for `gemini-2.0-flash` and `gemini-3.1-flash-lite` for\n`gemini-2.0-flash-lite`, while Vertex lists `gemini-3.5-flash-lite` for both. Voice and audio models have their own\ndeadline. On the Gemini API, `gemini-3.1-flash-live-preview`,\n`gemini-2.5-flash-native-audio-preview-12-2025`, `gemini-2.5-flash-preview-tts`,\n`gemini-2.5-pro-preview-tts` and `gemini-3.1-flash-tts-preview` all shut down on November 17, 2026,\nin favor of `gemini-3.8-live` and the `gemini-3.8-flash-tts` models. On Vertex,\n`gemini-live-2.5-flash-native-audio` retires on December 13, 2026.\n\nIf you need a Pro-class model rather than a Flash one, note that Vertex lists only Flash models as\nthe replacement for 2.5 Pro. The Pro-class options are `gemini-3.1-pro-preview`, which is still a\npreview, and `gemini-4-argon`, the flagship released October 13, 2026, which comes with its own\nmigration notes: it does not support explicit caching, and Google asks for HTTP timeouts of at\nleast 20 minutes per call.\n\n## ## Why the same model has two retirement dates\n\nThe Gemini API and Vertex are separate products with separate lifecycle policies, and the\nOctober 20 retirement only applied to Vertex. Which one your code hits depends on how the client\nis built, not on the model string. With the `google-genai` SDK, a client created with\n`vertexai=True` (or through the environment variables that select Vertex, such as\n`GOOGLE_GENAI_USE_VERTEXAI`, plus a project and location) runs on Vertex. A client created with an\nAPI key runs on the Gemini API.\n\nThe two policies also promise different things:\n\n- +**Vertex** splits models into two tables. Models in the first are available for at least 12\nmonths 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\nat least 45 days out. Vertex dates can be extended but are never moved earlier.\n- +**The Gemini API** lists the earliest date a model might be shut down and promises to\ncommunicate the exact date in advance. Once a model is shut down, its endpoint is gone.\n\nSo 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.\n\n## ## The deprecations that don't fail: auto-routing and -latest aliases\n\nA shutdown is loud. Your calls fail and someone gets paged. Two kinds of change on the Gemini API are quiet:\n\n- +**Auto-routing.** The Gemini API sends requests for`gemini-3.5-flash` to`gemini-3.6-flash` , and\nrequests for`gemini-3.7-flash` to`gemini-3.8-flash` . If you call either ID, you have already\nmigrated, without a test run and without a diff.\n- +**`-latest` aliases.** An ID like`gemini-flash-latest` is hot-swapped with every new release of\nthat model. Google promises two weeks' email notice for breaking changes, and nothing for the\nrest.\n\nBoth 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:\n\n``` python\nfrom google import genai\n\nclient = genai.Client()\nresp = client.models.generate_content(model=\"gemini-3.7-flash\", contents=\"ping\")\nprint(resp.model_version)  # the model that actually served the request\n```\n\nAn alert on a change in `model_version` per route catches a swap the day it happens, instead of\nwhen a downstream count drifts.\n\n## ## Step 1: inventory every Gemini model ID and the surface it runs on\n\nModel 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:\n\n```\ngrep -rhoE \"(gemini|text-embedding)-[a-z0-9.-]*[0-9][a-z0-9.-]*|gemini-[a-z-]*latest\" \\\n  --exclude-dir={node_modules,.git,.venv,dist} . | sort | uniq -c | sort -rn\n```\n\nFor 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.\n\nTwo kinds of model need more than a string change. Embedding models are one: vectors from\ndifferent embedding models are not comparable, so moving from `gemini-embedding-001` to\n`gemini-embedding-2` means re-embedding your whole index and re-checking retrieval quality, not\njust changing the query-side call. Tuned models are the other. If you fine-tuned a 2.5 model on\nVertex, check what the replacement supports before you plan around it. A forum thread from\nAugust 2026 points out that Vertex documents batch inference as unsupported for tuned Gemini 3\nand higher models.\n\n## ## Step 2: look up each date on the page for that surface\n\nPut each ID from step 1 against the deprecations page for its surface: the\n[Gemini API page ↗](https://ai.google.dev/gemini-api/docs/deprecations) for API keys, the\n[Vertex page ↗](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions)\nfor Vertex clients. Sort by date. Anything already past its date is an outage or an unplanned\nmigration you have already shipped. Anything inside 45 days is this sprint.\n\n## ## Step 3: choose a pinned replacement, not an alias\n\nUse the replacement Google lists, as a pinned ID, and check its own row before you commit to it.\nThe obvious trap right now: on the Gemini API, `gemini-2.0-flash` lists `gemini-3.6-flash` as its\nreplacement, and on Vertex `gemini-3.6-flash` retires on November 19, 2026. Migrating onto a model\nwith a short clock means doing this twice. `gemini-3.8-flash` is listed on Vertex as available\nuntil at least September 2, 2027, and it is the ID most of the table above points to.\n\nA `-latest` alias looks like a way out of the deprecation treadmill. It is the opposite: it swaps\nthe model under you with every release, and you lose the before-and-after comparison that makes a\nmigration safe.\n\n## ## Step 4: update the request for Gemini 3.8 Flash\n\nGoogle's [developer guide to Gemini 3.8 Flash ↗](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/guides/gemini-3-8-flash)\nlists what changes in the request. Coming from 2.5, these are the lines that matter:\n\n| In your 2.5-era request | On `gemini-3.8-flash` | What to do | \n|---|---|---|\n| `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 | \n| `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 | \n| `thinking_level: MINIMAL` | API validation error | Use `LOW` | \n| `candidate_count` ,`frequency_penalty` ,`presence_penalty` | API error | Remove them | \n| A prefilled model turn, or history ending on a `model` turn | Unsupported | Remove it. Use structured output to force a format | \n| 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 | \n| 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 | \n\nThe ignored `temperature` is the dangerous row, because nothing fails. Code that set\n`temperature=0` to make a classifier repeatable keeps running on 3.8 Flash and is no longer\nrepeatable. If you target a Gemini 3 Pro-class model instead, Google's advice runs the other way:\nkeep `temperature` at its default of 1.0, because lower values can cause looping or degraded\noutput. PDF and video inputs also change token counts under Gemini 3's `media_resolution` settings,\nso check the cost of any document-heavy route.\n\n## ## Step 5: replay production traffic on both models and diff the behavior\n\nEverything 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.\n\nThe method, in brief:\n\n- +**Build the cases from production logs** , not from prompts you make up: 100 to 300 real inputs,\nstratified by route, with what production actually did (tool calls, arguments, JSON fields)\nstored as the expectation.\n- +**Assert deterministically first.** Check the tools called, the argument formats, and field\nequality on every enum. Use an LLM judge only for free text, and treat its results as advisory.\n- +**Take several samples per case on 3.8 Flash.** With`temperature` ignored, one sample cannot\ntell a regression from sampling noise. Score the fraction of samples that pass.\n- +**Compare per route, never one average.** A 5% drop on one route disappears in the overall\nnumber.\n\nThere is one timing problem specific to this deprecation. If you are on Vertex, 2.5 is already\ngone, so the only baseline you have is what you logged before October 20. If you are on the Gemini\nAPI and your project still has 2.5 access, record a baseline run now, while the old model still\nanswers. The same applies to `gemini-3.6-flash` on Vertex before November 19.\n\nThe full walkthrough of this step, with code and the six regressions it caught on a real model\nupgrade, is in\n[How to catch LLM regressions before a model upgrade ships](https://www.evalshift.dev/blog/llm-regression-testing-model-upgrade).\n\n## ## Step 6: cut over with a rollback path\n\nSwitch one route at a time, behind a flag, starting with the route the diff in step 5 cleared\nmost clearly. Where the old model still answers (Gemini API projects with 2.5 access, Vertex\n`gemini-3.6-flash` until November 19), keep it as the fallback until the new route has run for a\nweek. Watch error rates, latency, cost and `model_version` per route. Then add the replacement's\nown retirement date to the team calendar, with a reminder 45 days ahead, because this checklist\nwill run again.\n\n## ## Doing this with EvalShift\n\nDisclosure: I'm the founder of EvalShift, and step 5 is the part it automates. The capture SDK\nwraps the `google-genai` client and records real runs, including tool calls and the generation\nconfig, and `compare` replays them against the candidate model:\n\n``` python\nfrom google import genai\nfrom evalshift import capture\nfrom evalshift.adapters.genai import wrap_genai\n\nclient = wrap_genai(genai.Client())  # records each call inside a capture session\n\nTOOLS = [...]  # the function declarations the agent is offered, or [] for none\n\n@capture.agent(suite=\"support\", redact=True, tools=TOOLS)  # no-op unless EVALSHIFT_CAPTURE=1\ndef handle_ticket(message): ...\npip install evalshift\nEVALSHIFT_CAPTURE=1 python my_agent.py   # record production-shaped runs\nevalshift capture sync                   # recorded runs -> golden suite\nevalshift compare --suite-name support --to gemini-3.8-flash\n```\n\nBoth arms are live calls, so run it while the old model still answers. When it no longer does,\nthe tool evaluators can still score the candidate against the trace production recorded\n(`against: expected`). For the ignored `temperature`, set `defaults.samples_per_example` above 1\nso each case is sampled several times. The verdict comes from a `migration_policy` written before\nthe run, and the report shows the per-example diff. Docs:\n[/docs/sdk-adapters](https://www.evalshift.dev/docs/sdk-adapters), [/docs/evaluators](https://www.evalshift.dev/docs/evaluators),\n[/docs/migration-policy](https://www.evalshift.dev/docs/migration-policy).\n\n## ## FAQ\n\n**Is Gemini 2.5 Flash deprecated?** On Vertex AI, yes: `gemini-2.5-flash`, `gemini-2.5-pro` and\n`gemini-2.5-flash-lite` retired on October 20, 2026. On the Gemini Developer API they are not\ndeprecated and have no shutdown date, but Google limits access to projects that have already used\nthem and recommends `gemini-3.8-flash` or `gemini-3.5-flash-lite` for new work.\n\n**What happens when a Gemini model is shut down?** The endpoint is turned off and requests to that\nmodel ID fail. Google documents no automatic redirect for the retired 2.5 models on Vertex. The\nexceptions are `gemini-3.5-flash` and `gemini-3.7-flash` on the Gemini API, which keep working by\nrouting requests to `gemini-3.6-flash` and `gemini-3.8-flash`.\n\n**How much notice does Google give before retiring a Gemini model?** On Vertex, models in the\nstandard table are available for at least 12 months after release. Shorter-lived models get a\nfixed retirement date at least 45 days ahead, and dates are never moved earlier. On the Gemini\nAPI, listed dates are the earliest possible shutdown, and `-latest` aliases get two weeks' email\nnotice before a breaking swap.\n\n**What should replace Gemini 2.5 Pro?** Vertex lists `gemini-3.8-flash` or `gemini-3.5-flash`.\nIf you need Pro-class reasoning, the options are `gemini-3.1-pro-preview`, which is still a\npreview, or the flagship `gemini-4-argon`. Replay real traffic on whichever you pick: a Flash model\nreplacing a Pro one is the swap most likely to change behavior on hard cases.\n\n**Should I use gemini-flash-latest to avoid future deprecations?** No. A `-latest` alias is\nhot-swapped with every new release, so it trades one planned migration for many untested ones.\nPin a version and run the migration checklist when its date comes.\n\n## ## Keep reading\n\n- +[How to catch LLM regressions before a model upgrade ships](https://www.evalshift.dev/blog/llm-regression-testing-model-upgrade) — step 5 in full, with code and the six failures it caught.\n- +[What actually breaks when you switch LLMs](https://www.evalshift.dev/blog/what-breaks-when-you-switch-llms) — why the\nworst regressions from a model swap read as correct.\n- +[Build a golden eval suite from production traffic](https://www.evalshift.dev/blog/build-a-golden-suite-from-production-traffic) — capturing the baseline before the old model is gone.\n- +[Evaluating agent tool calls](https://www.evalshift.dev/blog/evaluating-agent-tool-calls) — what to check when the\nagent's trace matters more than its text.", "url": "https://wpnews.pro/news/gemini-model-deprecation-dates-replacements-and-a-migration-checklist", "canonical_source": "https://www.evalshift.dev/blog/gemini-model-deprecation-migration-checklist", "published_at": "2026-10-26 00:00:00+00:00", "updated_at": "2026-10-26 22:42:55.364596+00:00", "lang": "en", "topics": ["large-language-models", "generative-ai", "ai-products", "developer-tools"], "entities": ["Google", "Gemini", "Vertex AI", "Gemini Enterprise Agent Platform", "gemini-2.5-pro", "gemini-3.8-flash", "gemini-3.6-flash", "Gemini Developer API"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/gemini-model-deprecation-dates-replacements-and-a-migration-checklist", "markdown": "https://wpnews.pro/news/gemini-model-deprecation-dates-replacements-and-a-migration-checklist.md", "text": "https://wpnews.pro/news/gemini-model-deprecation-dates-replacements-and-a-migration-checklist.txt", "jsonld": "https://wpnews.pro/news/gemini-model-deprecation-dates-replacements-and-a-migration-checklist.jsonld"}}