When a model is retired

Switching models safely, the next lesson, covers a move you choose. This lesson covers the one you do not. Every id you call has a date after which it stops working, and the provider sets that date, not you.

1.A retirement is announced, then it happens

Providers describe a model's life in a few stage words. As of Oct 2026, Anthropic uses four: Active, Legacy, Deprecated and Retired. A deprecated model still works, but it comes with a named replacement and a retirement date. Once it is retired, requests to it fail. OpenAI also marks models deprecated and legacy, but its definitions differ from Anthropic's, so read the definitions on each page.

How long is the window? Each provider publishes a minimum, and these are the numbers as of Oct 2026.

Real runs show how little room that can be. Anthropic gave 62 days for Claude Sonnet 4, and 61 days for a later model announced on 30 September 2026 for retirement on 30 November. OpenAI announced on 14 October 2026 that several GPT-4o and GPT-4.1 snapshots leave on 14 January 2027, about 92 days. That is shorter than the six months its page promises for generally available models, and the page gives no reason. Google set a shutdown of 9 March 2026 for a preview model released 18 November 2025, under four months later.

Features retire too: OpenAI's Assistants API shut down on 26 August 2026.

A date on an active model is a floor. A date in a notice is the date.

A floor can pass in silence. On 17 October 2026 one active model's earliest date, 15 October, was two days gone and it was still listed as active. That does not make it safe. A notice could arrive any day.

2.What the id tells you, and what it cannot

An id can be a snapshot, which is fixed, or a pointer, which moves. You need to know which one you hold.

On Anthropic, as of Oct 2026, ids from the 4.6 generation onward have no date in them, for example claude-sonnet-5-5. Such an id is a snapshot, not a pointer: the weights and configuration under it do not change, and an update ships under a new id. Before 4.6, ids carry a date, and the Claude API also accepts a shorter alias that moves to the newest snapshot of that version. Every id, dated or not, has its own retirement schedule.

Google works differently. As of Oct 2026, its models page says stable models usually do not change, and a -latest alias is swapped on every new release, with two weeks' email notice before breaking changes. So an id that answers does not prove which model answered. This is why the next lesson, Switching models safely, returns the served id with every response, and why you log it.

For OpenAI the pages used here list dated snapshots such as gpt-4o-2024-08-06. The undated gpt-4o and gpt-4.1 showed the same shutdown date in the models list on 17 October 2026. That tells you they retire together. Whether an undated id is a fixed snapshot is not stated on the pages used here, so it is not confirmed.

Two more things matter. As of Oct 2026, Amazon Bedrock and Google Cloud, which also host Claude, set their own retirement schedules, so the same model can have a different date there. And a pinned id fixes the weights, not everything around them: as of Oct 2026, Anthropic's id page says the router, safety classifiers and sampling code can change under an unchanged id. Timeouts, fallbacks, and failures that look like success covers what that looks like in practice.

3.Find your exposure before the email does

You survive a retirement if you know what you call. Look in four places.

1. Your code. Search every repository for model strings. The script below does this.
2. Your running config. Environment variables, feature flags, a config service, notebooks, and the other team's service that shares your key.
3. The provider's own records. As of Oct 2026, Anthropic's Console has a Usage page with an Export button that gives a CSV of usage by API key and model, and OpenAI's models list carries a shutdown_date field on its model objects.
4. A calendar. Put each date in the calendar you use for certificate expiry, with a margin well before it, because the work after a notice is real work.

Here is a failure case from this course itself. Its first edition pinned one Anthropic id in eleven places across eight lessons. That id was retired on 15 June 2026, 62 days after its notice, and every sample stopped working. A search would have found all eleven in a minute. The same trap exists on the OpenAI side. On 17 October 2026 a call to a model id that OpenAI retired in July 2025 returned a 404 model_not_found: "does not exist or you do not have access to it". A retired model looks like a typo or a permissions problem, so people debug the wrong thing.

# python3 find_models.py path/to/repo   -- set OPENAI_API_KEY to look up OpenAI dates
import json, os, re, sys, urllib.request
from datetime import date
from pathlib import Path

ROOT = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
SKIP = {".git", "node_modules", ".venv", ".next"}
SUFFIXES = {".py", ".ts", ".js", ".json", ".yaml", ".yml", ".toml", ".env"}
PATTERN = re.compile(r"\b(?:claude|gpt|gemini|o\d)-[a-z0-9][a-z0-9.\-]*")

# Add Anthropic and Google ids by hand from their deprecations pages: "id": "YYYY-MM-DD".
MANUAL = {}

found = {}  # model string -> first place it appears
for path in ROOT.rglob("*"):
    if path.is_dir() or SKIP & set(path.parts) or not (path.suffix in SUFFIXES or path.name.startswith(".env")):
        continue
    for n, line in enumerate(path.read_text(errors="ignore").splitlines(), 1):
        for m in PATTERN.findall(line):
            found.setdefault(m.rstrip(".-"), f"{path}:{n}")

# OpenAI: every model object has an optional shutdown_date, "YYYY-MM-DD" or null.
dates = {}
key = os.environ.get("OPENAI_API_KEY")
if key:  # without a key, OpenAI ids print "no date known"
    req = urllib.request.Request("https://api.openai.com/v1/models",
        headers={"Authorization": "Bearer " + key})
    dates = {m["id"]: m.get("shutdown_date") for m in json.load(urllib.request.urlopen(req))["data"]}
dates.update(MANUAL)

for model, where in sorted(found.items()):
    d = dates.get(model)
    days = (date.fromisoformat(d) - date.today()).days if d else None
    left = "no date known" if days is None else "already past" if days < 0 else f"{days} days"
    print(f"{model:30} {left:14} {where}")

# Run on 2026-10-17 against a small test repo, it printed:
# claude-sonnet-4-20250514       no date known  repo/src/config.py:4
# claude-sonnet-5-5              no date known  repo/src/config.py:3
# gpt-4o                         89 days        repo/src/config.py:2
# gpt-4o-2024-08-06              89 days        repo/src/config.py:1
# gpt-5.1-codex-max              already past   repo/src/config.py:6

Run it from the root of a repository. It prints each model string, the days left and where it was found. Anthropic and Google ids say "no date known" until you add them to MANUAL, because the pages used for this lesson describe no API field for their dates. "No date known" means the script does not know, not that no date exists. The first line of that output is the retired id from the failure case, still sitting in a file. The "already past" row shows that the models list still returns ids whose date has gone by, so it is a source of dates, not proof that a model answers.

When this does not apply. The routine matters most for production calls. Several cases need less.

• Open weights you host. A file on your own disk does not get retired. Your risk moves to the licence and to your hardware, as Open weights vs closed APIs and Running a model yourself explain. As of Oct 2026, Anthropic says it has committed to keeping the weights of its publicly released models, but that preserves them, it does not keep them callable.
• Throwaway scripts and notebooks. If it is run twice and deleted, let it break.
• A date a year away. A far-off floor needs a calendar entry, not a migration. A new model shipping is not a notice either. Migrate when a notice names a date, or when you want the new model.
• Ids your search cannot see. The script reads files. If your ids live in a config service, use the provider's usage export.