Model lifecycle

What a model identifier promises, what happens when weights change, and how long a superseded identifier keeps serving.

The promise a model identifier makes is the one thing you cannot check at runtime, so it is written down here.

An identifier is pinned to its weights

A weight change is published under a new identifier. It is never applied in place. If you send traffic to atlas-mid-1 today and again in three months, you are talking to the same weights, or you are talking to a 404. You are never silently talking to something else.

This is what makes an evaluation you ran last quarter still mean something. A provider that swaps weights behind a stable name has made every one of your prompt-level measurements expire without telling you.

Atlas records the backend's system_fingerprint per identifier and alerts internally when it changes against a pinned one, including when a backend that used to report a fingerprint stops. This is the control that makes the paragraph above enforceable rather than merely intended.

The states you can observe

GET /v1/models publishes a lifecycle object on every entry:

`status`	Meaning	Serving?
`active`	The current identifier for its rung.	Yes
`superseded`	A newer identifier exists; this one is in its deprecation window.	Yes, until `shutdown_at`

{
  "lifecycle": {
    "status": "superseded",
    "superseded_by": "atlas-mid-1",
    "shutdown_at": "2026-11-10T00:00:00.000Z"
  }
}

superseded_bystring | null

The identifier that replaces this one. null while status is active.

shutdown_atstring | null

When this identifier stops serving, as an ISO 8601 timestamp. null while status is active. Once this passes, the identifier is retired.

Atlas tracks operational states beyond these two internally, but does not publish them. In particular there is no health signal on this endpoint: a model having a bad hour is an Atlas problem, and telling you an identifier is "alerting" while it is still serving your traffic normally would be noise you cannot act on.

The deprecation window

When an identifier is superseded, it keeps serving its original weights for a published minimum period — 90 days by default — before it is retired. The exact date is always on the model itself as shutdown_at; the default is the floor, not the schedule.

That window is a quarter deliberately: it spans one planning cycle, which is the unit at which a team can actually schedule a migration and re-run its evaluations.

When an identifier is gone

A retired identifier returns 404 — but with a code that distinguishes it from a typo:

model_retired means the pin you were relying on has expired and there is a successor to move to. model_not_found means the identifier was never published. Both are 404 so existing client error handling works unchanged; the code is what lets your alerting tell a deadline you missed from a bug.

What to do about it

Read lifecycle from GET /v1/models on a schedule, not once at integration time. A status of superseded on an identifier you are pinned to is your migration notice, and it arrives with a date attached.
Treat shutdown_at as a deadline in your own tracker. Atlas will not extend an identifier past its published date on request; the point of the published minimum is that it is the same for everyone.
Re-run your evaluations against superseded_by before you switch. A new identifier is new weights. Nothing about the naming implies the new rung behaves like the old one on your prompts.