All postsAI

A model lifecycle policy for AI features: pins, evals, an owner and a calendar

Hosted models retire on a schedule. What OpenAI, Anthropic and Google promise, how to detect retirements automatically, and how to switch safely.

Johnny Unar7 min read

01

models are dependencies with an expiry date

Every LLM feature depends on a model that its provider will retire, usually within a year or two of launch. For a small team that ships a feature and moves on, the retirement notice arrives by email to whoever created the API account, nobody connects it to the feature, and on the shutdown date the calls start failing. On OpenAI a request for a model that no longer exists comes back as a 404 with the error code model_not_found, and Anthropic's deprecations page says plainly that requests to retired models fail.

Retirement is the loud failure. The quieter one is a model identifier that floats, so the model behind it changes without a deploy and the feature's behaviour shifts with nothing in your git history to explain it. Both have the same fix, which is to treat the model like any other pinned dependency: a known version, a test suite that has to pass before the version changes, a named owner and a date in a calendar.

02

what the providers actually promise

OpenAI's deprecations page commits to at least six months' notice before retiring a generally available model, at least three months for specialized variants such as Codex or deep research models, and possibly much shorter notice, such as two weeks, for models with "preview" in the name. Customers actively using a model get an email, and the deprecation is listed on that page. Read the actual entries as well as the policy, though: the notice dated 14 October 2026 retires the GPT-4o, GPT-4o mini, GPT-4.1 and GPT-4.1 mini snapshots on 14 January 2027, three months later.

Anthropic promises at least 60 days' notice before retiring a publicly released model, by email to customers with active deployments and in the documentation. Its lifecycle has four stages (active, legacy, deprecated, retired), and the deprecations page lists a tentative "not sooner than" retirement date for every active model. Claude Sonnet 4.5 is a recent example: deprecated on 30 September 2026 and retiring on 30 November 2026, a little over the minimum. Those dates apply to Anthropic-operated platforms, and Bedrock and Google-managed Vertex deployments set their own schedules.

Google's Gemini docs recommend a specific stable model for production. Preview models can be deprecated with at least two weeks' notice, and the -latest aliases are swapped to each new release with two weeks' email notice. The practical rule across all three is to plan for the shortest notice anyone has actually given, which today is weeks for previews and about two to three months for everything else.

03

pin what you can and log what you can't

Pinning means different things per provider, and it's worth knowing exactly what your identifier refers to. On OpenAI, a model like gpt-5.4-mini has a dated snapshot, gpt-5.4-mini-2026-03-17, and a call to the short name reports the snapshot in the response's model field. Newer models such as the GPT-6 family are listed under a single ID with no dated variant in the models list as of November 2026, so that ID is all you can pin, and logging the model field from each response is how you'd notice if that ever changes.

Anthropic changed its scheme with the 4.6 generation. Its models overview says every Claude model ID is a pinned snapshot, including the dateless ones like claude-sonnet-5-5. Older models have an alias that points at a dated ID, so claude-opus-4-5 resolves to claude-opus-4-5-20251101, and for those the dated form is the pin.

The model ID isn't the whole contract. Anthropic removed temperature, top_p and top_k in API version 2026-10-21, where sending them returns a 400, and earlier API versions already reject non-default values on Claude 4.7 and later. OpenAI's GPT-6 models reject temperature at their default reasoning settings as well. So the pin is really the model ID, the API version and the set of parameters you send, and the eval gate below has to cover all three.

04

one policy file per feature

The policy doesn't need to be a document anyone reads front to back. A small file in the repository that the CI job parses works better, because the check and the policy can't drift apart. Each feature gets an entry with its provider, the pinned model, the person who owns the decision and the eval set that has to pass before the pin changes:

toml
1[invoice_extraction]
2provider = "openai"
3model = "gpt-4.1-mini-2025-04-14"
4owner = "jana"
5eval = "evals/invoice_extraction.jsonl"
6
7[support_reply]
8provider = "anthropic"
9model = "claude-sonnet-5-5"
10owner = "petr"
11eval = "evals/support_reply.jsonl"

Next to it, keep a short note per feature with the things a script can't check: what the feature does when the model call fails (a cached answer, a smaller model, or an honest error message), when the eval set was last refreshed with real inputs, and the date and result of the last model switch. The owner should be a person, not a team, because "the backend team" doesn't answer an email about a retirement.

05

checking retirement dates automatically

Both providers now expose lifecycle data through their models endpoints, which makes the check a short script instead of a reminder. OpenAI's GET /v1/models returns a shutdown_date on each model object, documented as the date the model will shut down or null if none has been announced. Anthropic's GET /v1/models/{model_id} returns lifecycle (active, deprecated or retired), deprecated_at and retires_at, where retires_at stays null while the model is active.

python
1import json
2import os
3import sys
4import tomllib
5import urllib.error
6import urllib.request
7from datetime import date, timedelta
8
9WARN_DAYS = 90
10
11
12def get_json(url, headers):
13 req = urllib.request.Request(url, headers=headers)
14 with urllib.request.urlopen(req, timeout=30) as resp:
15 return json.load(resp)
16
17
18def openai_retirement(model):
19 data = get_json(
20 "https://api.openai.com/v1/models",
21 {"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
22 )
23 for m in data["data"]:
24 if m["id"] == model:
25 d = m.get("shutdown_date")
26 return date.fromisoformat(d) if d else None
27 raise LookupError(f"{model} is not listed for this key")
28
29
30def anthropic_retirement(model):
31 try:
32 m = get_json(
33 f"https://api.anthropic.com/v1/models/{model}",
34 {"x-api-key": os.environ["ANTHROPIC_API_KEY"], "anthropic-version": "2026-10-21"},
35 )
36 except urllib.error.HTTPError as err:
37 raise LookupError(f"{model}: HTTP {err.code}") from err
38 if m["lifecycle"] != "active":
39 raise LookupError(f"{model} is {m['lifecycle']}, retires_at={m['retires_at']}")
40 return None
41
42
43CHECKS = {"openai": openai_retirement, "anthropic": anthropic_retirement}
44
45
46def main(path):
47 features = tomllib.load(open(path, "rb"))
48 problems = []
49 for name, f in features.items():
50 try:
51 retires = CHECKS[f["provider"]](f["model"])
52 except LookupError as err:
53 problems.append(f"{name}: {err} (owner: {f['owner']})")
54 continue
55 if retires and retires - date.today() <= timedelta(days=WARN_DAYS):
56 problems.append(f"{name}: {f['model']} retires {retires} (owner: {f['owner']})")
57 print("\n".join(problems) or "all pinned models ok")
58 return 1 if problems else 0
59
60
61if __name__ == "__main__":
62 sys.exit(main(sys.argv[1]))

Run against OpenAI's live models list on 8 November 2026, the GPT-4.1 mini entry in the example file fails the check, because its shutdown date is 67 days away:

text
1invoice_extraction: gpt-4.1-mini-2025-04-14 retires 2027-01-14 (owner: jana)

Any Anthropic model that isn't active fails immediately, since a deprecated model is closed to new adopters and already has a retirement date. Run the script weekly as a scheduled CI job that opens an issue assigned to the owner, and keep two safety nets in case the job breaks quietly: an alert on model_not_found and other 404s from the model API in production, and a subscription to the providers' deprecation pages for whoever owns the AI budget. Anthropic's Console can also export usage by API key and model as CSV, which is the quickest way to find a forgotten integration still calling an old model.

06

the eval gate before any switch

When the check fires, or a cheaper model comes out (Anthropic's current price list has Haiku 5.5 input at a tenth of Haiku 4.5's), the owner runs the feature's eval set against the candidate before touching the pin. For structured output that means field-level assertions on real inputs, run several times per case and gated on a pass rate, because a single run tells you little about a sampled model. For free text, a rubric graded by a model plus a human reading a sample of the diffs is a reasonable floor. Cosine similarity between old and new answers is a weak signal, since a paraphrase scores high and a single dropped "not" barely moves it. The mechanics of that test setup are covered in more detail in our post on shipping prompts like code.

The switch itself is an ordinary pull request that changes the pin and includes the eval numbers for the old and new model, followed by a staged rollout if the feature has enough traffic to compare. Keep the previous model configured as the fallback until its own retirement date, and test that fallback path deliberately: set the model to an ID that doesn't exist in a staging environment and click through the feature, because error handling written months ago for a UI that has since changed is the part most likely to be broken.

Put every retirement date from the check into a shared team calendar with the owner invited, and review each feature's pin once a quarter even when nothing is retiring. Prices and capabilities move fast enough that a feature left on its launch model for a year is usually paying more than it needs to for worse results.

Thanks for reading.
Johnny Unar

Written by

Johnny Unar

Keep reading

Stop patching.Start building.

Tell us what's slowing you down. We'll bring coffee and opinions.