Say when a model retires and what replaces it

A date and a name, on the page

When a model is retired, buyers need two facts: the date requests to it will stop working, and the model you recommend instead. Both belong on the model's own page and in its API documentation, as plain text with the date in a full format, from the day retirement is decided. An email to account holders reaches the person who signed up, who may have left. The page reaches whoever is debugging the failure.

Everything else in a retirement notice is detail around those two facts, and none of it helps a buyer who cannot find the date.

Machine-readable warnings help as well. Where your API returns a header or a field saying a model is deprecated, document it on the same page, so a buyer can make their own systems raise an alert long before the date.

Deprecated, retired and removed are separate dates

Makers use the words loosely, and buyers act on them differently. Deprecated usually means do not start new work on this. Retired or shut down usually means requests fail. Some makers have a stage between where the model still answers but slower, or only for existing accounts. Say which stages your process has and give each its own date.

A buyer plans a migration around the last date, not the first. A page that says deprecated in March and nothing more leaves them to panic early or to wait until requests start failing.

Dated snapshots and point releases can be retired with less ceremony than whole models, because the maker sees them as versions of one thing. The buyer pinned to a snapshot sees a model that will stop answering. Each dated identifier needs its own retirement date on the page, even where the replacement is just the next snapshot.

Moving aliases need a sentence too. If an alias such as latest will point somewhere new when a snapshot retires, say when the alias moves, separately from when the old identifier stops. Those are different events, and they affect different buyers.

How much notice is enough

There is no standard period, and this site holds no record of what makers give. What can be said is that notice has to cover a buyer's whole cycle: noticing, testing the replacement, changing code, getting the change reviewed and released. With the model inside a regulated product that can take months, and a short notice turns a planned migration into an outage.

State the notice period as a policy, once, on a page that covers every model, and then keep to it. For a long project the policy can matter as much as the model, because it says how long the choice stays safe.

Naming the replacement is a claim, so make it carefully

Pointing at a replacement says it will do the old model's job, and buyers will hold you to that. Say what is the same and what is not: price per million tokens, context length, output limit, modalities, the chat format, the tokenizer. If the replacement is dearer per token but uses fewer tokens, say both, and do not let the buyer discover the first half on an invoice.

If there is no like-for-like replacement, say that too. A buyer told plainly that the nearest successor costs more or lacks a feature can plan. A buyer told that a new model is better in every way, and finding it is not, stops trusting your release notes, which were covered in what release notes should say.

Where the replacement needs a different prompt format, link a short migration guide that shows an old request and the equivalent new one. It is an easy change to miss, and one worked example does more than a paragraph describing it.

What happens at hosts and in price tables

If the weights were published, hosts may keep serving a model long after its maker stops. If they were not, the model will usually stop answering at every seller on your date. Either way, sellers update their pages on their own schedule, and for a while a buyer can find the old model priced in one place and gone in another.

On the token price table, which holds 750 input-price listings, a rate older than 21 days is hidden rather than shown stale. When a retired model's price disappears from a seller's page, the last reading of it ages out of the table. The retirement date on your page is what tells a buyer whether that gap is a retirement or a seller's oversight.

Directories have the same lag. A listing that still shows a retired model as current is wrong for want of a stated date, and a maker that claims its listing can correct it with the page that states the retirement.

Keep the page after the model is gone

Do not delete a retired model's page. Replace the body with the retirement date, the replacement and a link to the migration notes, and keep it at the same address. Old code, old prompts and old blog posts still name the model, and a buyer following any of them should land on an answer, not an error page.

The identifier matters here more than anywhere. If the replacement's identifier follows the same naming grammar, a buyer can often guess the migration from the string alone.

Keep the old model's facts on that page as well: its context length, its last price, its license. Buyers comparing the replacement need the baseline, and the page is the only place the maker still states it.