A deprecation notice reads like a lot of time. Schedule it backwards from the retirement date and the usable window is roughly half what the headline number suggests.
How much notice you actually get
The published commitments differ enough between providers that it is worth knowing which one you are planning against, and they are the first thing to check when a notice lands.
Anthropic’s deprecation documentation, as published at the time of writing, commits to at least 60 days’ notice before retirement for publicly released models, notifying customers with active deployments by email and in the documentation. It also defines a four-stage lifecycle — active, legacy, deprecated, retired — where legacy means the model still works but will receive no updates, deprecated means a retirement date has been assigned, and retired means requests fail. Anthropic’s model deprecations page carries both the policy and the dated table.
OpenAI’s deprecations page, also at the time of writing, states at least six months’ notice for generally available models, at least three months for specialised variants, and warns that preview models may be retired with much shorter notice — as little as two weeks. OpenAI’s deprecations documentation is the authority for the current values.
Two consequences. Preview and specialised model strings carry materially less notice than the flagship ones, which is a fact to weigh when choosing what to depend on, not something to discover in an email. And the notice period is a floor, not a plan: it says when the model stops answering, not when your work has to be finished.
Notice periods are policy, and policy changes. Both figures above are as documented at the time of writing. Check the provider’s own page when a notice arrives rather than relying on a remembered number.
Schedule backwards from the retirement date
Take a 60-day notice and lay it out from the end. Every item below is something that must finish before the one after it starts.
Day 60 Retirement. Requests to the old model fail.
Day 53 Hard buffer ends. Nothing ships after this except rollback.
Day 46 Cutover complete: 100% of traffic on the new model.
Day 32 Cutover begins: ramp 5% -> 25% -> 50% -> 100%, gated on metrics.
Day 25 Dual-run ends; decision made on the evidence it produced.
Day 11 Dual-run begins on sampled production traffic.
Day 4 Evaluation complete on the new model; prompts adjusted.
Day 0 Notice received. Inventory begins.
Usable engineering window: days 0-25. Twenty-five days, not sixty.
The two blocks people leave out are the buffer at the end and the decision gap in the middle. The buffer exists because a rollback needs somewhere to roll back to, and after the retirement date the old model is not there. A cutover that completes on the retirement date has no rollback at all; it is a deployment with the safety net removed on the same day. Finish a week early, deliberately.
The decision gap exists because the dual-run produces evidence that somebody has to read, disagree about and sign off. That is calendar time and it does not compress. If your organisation has a change freeze — end of quarter, a holiday period, an unrelated release — subtract it from the window before planning anything, because it will not move for you.
Week one is inventory, and it takes longer than you think
The task is to find every place the retiring model string can be produced. Not every place it is written down: every place it can be produced, which includes configuration, environment variables, database rows, feature flags, saved user preferences and anything a customer set two years ago.
- Pull the provider’s own usage export. Anthropic’s console exports a CSV of usage broken down by API key and model; comparable exports exist elsewhere. This is ground truth about what is actually calling the model, and it beats grep because it finds the caller nobody remembered.
- Grep the code for the model string, then grep for the variables that hold it, then grep for the aliases. Aliases are the dangerous case: an alias that silently resolves to the retiring version means the string appears nowhere and the traffic is real.
- Query the database for stored model choices. Anything persisted from a UI dropdown, a per-tenant setting or a saved workflow is a caller you cannot fix by deploying.
- Reconcile the two lists. Any key in the usage export with no corresponding code path is an unknown caller and is the highest priority item you have.
- Add an alert now on any request carrying the retiring model string, so the residual traffic is visible for the rest of the window and you find out on day 40 rather than on day 60.
Batch jobs deserve their own pass. A quarterly report that runs once during the window will not appear in a usage export taken on the wrong week, and it will fail on the day it next runs, which may be after retirement.
The dual-run, and when to stop it
A dual-run sends the same production input to both models and compares. It is the only part of this plan that produces evidence about your actual traffic rather than your test set, and it is the part most often cut for time.
Sample rather than duplicating everything — a few percent of traffic is usually enough to populate a distribution — and log both outputs with the input, keyed so they can be diffed offline. Compare on the metrics that have ground truth first, then on judged metrics with the re-baselining caveats that apply to any changed instrument.
Decide up front what would make you stop, and write it down before the data arrives. A dual-run with no exit criterion runs until someone gets bored, which is the worst possible stopping rule because it correlates with nothing. Give it a fixed duration and a named decision-maker, and treat “we need more data” on day 25 as the answer “we are not ready” rather than as a schedule extension.
Dual-running means calling two providers with one payload and diffing the results, which is mostly plumbing: two clients, two request shapes, two usage objects to reconcile. Anything that already fronts both providers behind one interface — Multigrid does this, and so does a hand-written adapter layer — turns the dual-run into a routing rule rather than a project. The comparison logic is yours either way, and it is the part worth spending the window on.
When the notice is much shorter
Preview models can carry two weeks. That is not a compressed version of the plan above; it is a different plan, and pretending otherwise is how teams end up cutting over with no evidence.
With a fortnight, drop the dual-run and rely on your offline evaluation set, cut over behind a flag that can be flipped in seconds without a deploy, and accept that you are trading evidence for time. Ramp in the same shape but over days rather than weeks, and keep someone watching.
The structural fix is upstream of any single notice. Putting the model version behind a feature flag converts a cutover from a deploy into a configuration change, which is the single largest reduction in how much calendar time a migration needs. Do it before the next notice arrives, not during it. And if the model is being retired while a commercial commitment still has months to run, the operational plan on this page is only half the work — the mid-contract case covers what to raise with the vendor and when.
Top comments (0)