Model Lifecycle
Every model in the Model Graph registry has a status that reflects where it is in its lifecycle. Understanding these stages is essential for keeping your AI integrations current and avoiding breaking changes.
Status Values
Active → Latest → Deprecated → Sunset
Active
The model is available and functional. It was once the latest version in its family but has since been superseded by a newer release. It continues to work normally — you can still use it in production — but it's no longer the recommended choice.
What to do: Consider upgrading to the latest model in the family when convenient. There's no immediate urgency, but newer models typically offer improved performance.
Latest
The current recommended version in its model family. When someone asks "what's the best Sonnet model?" — this is it. Each family has exactly one latest model at any time.
What to do: You're on the most current version. No action needed.
Deprecated
The model has been announced for removal by its provider. It still works today, but it has a deprecation_date and possibly a sunset_date indicating when it will stop functioning. Some providers give months of notice; others give weeks.
What to do: Plan your migration. Use the upgrade endpoint to find the recommended replacement. The resolve endpoint can give you a format-preserving replacement string for any alias format.
Sunset
The model has been shut down and no longer accepts requests. API calls using this model ID will fail. This is the terminal state.
What to do: If you're still referencing this model, you need to upgrade immediately. The registry retains sunset models for historical reference and to help tools detect stale references in code.
Lifecycle Timeline Example
Here's how the Claude Sonnet family has evolved:
| Model | Status | Release | Deprecation | Sunset |
|---|---|---|---|---|
| Claude 3 Sonnet | deprecated | 2024-02-29 | 2025-01-15 | 2025-07-01 |
| Claude 3.5 Sonnet | active | 2024-10-22 | — | — |
| Claude Sonnet 4.6 | latest | 2025-10-15 | — | — |
Successor Chains
When a model is deprecated, the registry tracks its successor — the model that replaces it. In most cases, the successor is simply the latest model in the same family. However, sometimes providers recommend a specific replacement that isn't the obvious next version (for example, a model in a different family).
The successor_model_id field on a model explicitly defines this chain. When it's set, the upgrade endpoint follows it instead of defaulting to latest.
Querying by Status
You can filter models by status using the models list endpoint:
# Find all deprecated models (migration candidates)
curl "https://api.modelgraph.ai/api/v1/models?status=deprecated"
# Find the latest version of every family
curl "https://api.modelgraph.ai/api/v1/models?status=latest"
# Find sunset models (broken references in code)
curl "https://api.modelgraph.ai/api/v1/models?status=sunset"