Model pinning
Definition
Model pinning is the practice of naming one exact, fixed model version in your code or settings, instead of a general name the provider can point at a newer model. It stops the model from changing under you before you have tested the new one.
By Ronan Liedmeier, fractional head of growth and course author · Published 17 October 2026 · Last updated 17 October 2026
Also called: version pinning, model snapshot
Without it, a workflow that behaved one way on Friday can behave differently on Monday because the model behind the name changed. Pinning lets you decide when that change happens, after you have tested it.
How it works
Providers offer two kinds of model names. A snapshot ID names one fixed release, often with a date in the name. An alias is a shorter convenience name that resolves to the latest snapshot in a family. Anthropic's documentation says the model behind a model ID stays constant for that ID's lifetime, that this guarantee does not extend to aliases, and that updated versions ship under new IDs.
Pinning has limits. Every pinned version has its own retirement date, and OpenAI lists a separate shutdown date for each dated snapshot, so a pin controls when you migrate while the provider still sets the last possible day. Anthropic also notes that changes to its serving infrastructure can occasionally cause small behavior differences even when the ID stays the same.
Example
A marketing analyst has a script that sorts ad search terms into intent buckets. She replaces the alias in the script with the snapshot ID, writes that ID and its retirement date into the workflow notes, and books a reminder to test the next version against 50 labeled search terms a month before the date.
Common mistake
Pinning and forgetting. Teams that never check the deprecations page learn that their pinned model was retired when requests start failing.
Learn it in AI Academy
- Building on Moving APIsAdvanced · 12 min
Related terms
- Model deprecation
- Model deprecation is when an AI provider announces that a model or API will be retired and sets a date after which requests to it stop working. Until then it still runs, but users are expected to move to a recommended replacement.
- Regression testing for AI
- Regression testing for AI is re-running a fixed set of test cases after any change to a prompt or model, to check that what worked before still works. It catches changes that raise the average score while breaking one specific case.
- AI eval (evaluation)
- An AI eval (evaluation) is a repeatable test that checks whether an AI prompt or workflow gives good answers, by running it on a fixed set of inputs and scoring the outputs against agreed criteria. It turns "seems fine" into a score you can compare.
- API (application programming interface)
- An API (application programming interface) is a set of requests a software service agrees to accept from other programs, a bit like a menu. A program sends a request such as "create a contact" and the service sends back data or a confirmation.