OpenAI model aliases vs snapshots: pin snapshots for stable behavior, track -latest drift

TL;DR

If you use an alias intentionally, log the resolved model on every deploy and diff it in CI, so a silent model swap shows up as a deliberate-looking change. When migrating off a deprecated model, adopt the deprecation page's recommended replacement and re-pin the new snapshot.

Steps

1. The mechanics:

• Dated snapshots (for example gpt-5-2025-08-07) are immutable: they behave the same until their shutdown date.
• Aliases (for example gpt-5-chat-latest, gpt-daybreak-red-latest) are pointers that OpenAI moves to newer models without notice.
• At shutdown, both aliases and snapshots for a retired model stop working.

2. What the agent should do:
3. Pin a dated snapshot in production configs for reproducible behavior and stable pricing.
4. If you use an alias intentionally, log the resolved model on every deploy and diff it in CI, so a silent model swap shows up as a deliberate-looking change.
5. When migrating off a deprecated model, adopt the deprecation page's recommended replacement and re-pin the new snapshot.
6. Keep model IDs in one registry (env var or config), not scattered across files, so a migration touches one place.
7. The trap: training evals or cost projections against an alias, then wondering why outputs or bills shifted. The alias did exactly what it is for; the mistake was treating a moving pointer as a version.
8. Evidence: https://platform.openai.com/docs/deprecations https://platform.openai.com/docs/models

When to use

You are seeing this: The mechanics: - Dated snapshots (for example gpt-5-2025-08-07) are immutable: they behave the same until their shutdown date. - Aliases (for example gpt-5-chat-latest, gpt-daybreak-red-latest) are pointers that OpenAI moves to newer models without notice.... Use this skill when you run into "OpenAI model aliases vs snapshots: pin snapshots for stable behavior, track -latest drift".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Sources

• https://platform.openai.com/docs/deprecations
• https://platform.openai.com/docs/models

Verified against official OpenAI docs 2026-09-26.