Pinning a Dated Mistral Model Version

mistral-large-latest is a pointer. It resolves to a dated snapshot, and Mistral moves it when a new one ships. Pinning replaces an upgrade that happens to you with one you schedule.

What an alias costs you

A family alias is convenient and it is the right choice for a prototype. In production it makes three things impossible.

• Reproducing a result. A bug report from last month references a model that no longer exists behind that name. Nothing you do reproduces it, including sending the same random_seed — the seed fixes the sampler, not the weights.
• Attributing a regression. When output quality moves and three things changed — your prompt, your retrieval, and silently the model — you cannot bisect. Pinning removes one variable permanently.
• Controlling when you take the risk. A new snapshot can change formatting habits, verbosity, refusal behaviour and how eagerly it calls tools. None of that is a bug in the new model; all of it can break a prompt tuned against the old one. With an alias, that lands on a Tuesday you did not pick.

The trade is that a pinned snapshot eventually retires. That is a scheduled, announced event you can plan around, which is strictly better than an unscheduled one, and step five below is how you find out in time.

There is a second, smaller cost worth naming so that the decision is made with both in view: a pinned model does not get better. Snapshot releases usually improve instruction following and reduce the rate of malformed structured output, and a service pinned for eighteen months is running a model that is worse than the one it could be running, at the same price or more. Pinning is not a permanent state; it is a way of controlling the date on which you take the change. Treat the pin as something you move deliberately every few months rather than something you set once.

Find the snapshot you are on

Pinning to a model you have never run is a gamble, so the first move is not to pick a snapshot from a list — it is to find out which one has been serving your traffic all along. That snapshot is the one your prompts were written against and the one your users have been happy with, which makes it the correct pin target and the one that requires no re-validation. The alias mapping in the models endpoint gives it to you directly.

1. List the models your key can reach. Each entry carries an id, and dated snapshots carry the aliases that currently point at them:

   curl -s https://api.mistral.ai/v1/models \
     -H "Authorization: Bearer $MISTRAL_API_KEY" \
     | jq -r '.data[]
              | [.id, ((.aliases // []) | join(",")), (.deprecation // "-")]
              | @tsv' \
     | sort

2. Read down the aliases column for the alias you are currently sending. The id on that row is the dated snapshot you have been using all along — something of the form mistral-large-2411, where the four digits are the year and month of the release. That id is your pin candidate.

3. Note the deprecation field on that row if it is populated. An already-dated retirement on the snapshot you are about to pin to means you should pin to the newer one instead and test now rather than pin to a model with weeks left.

Swap the alias for the snapshot

1. Put the id in configuration, not in a call site. You are going to change it every few months, and it should be one edit and a deploy rather than a search across the codebase:

   # .env
   MISTRAL_MODEL=mistral-large-2411
   
   # Record the reason next to it, because in four months nobody remembers.
   # Pinned 2026-08-11. Prompt suite validated against this snapshot.
   # Review when the deprecation check in CI starts warning.

2. Read it once, at the edge, and pass it everywhere:

   import os
   from mistralai import Mistral
   
   MODEL = os.environ["MISTRAL_MODEL"]      # fail loudly if unset
   client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
   
   resp = client.chat.complete(
       model=MODEL,
       messages=[{"role": "user", "content": "Summarise this ticket in one line."}],
       max_tokens=120,
       temperature=0.2,
   )
   print(resp.model)                        # what the server says it served

3. Grep for stragglers before you call it done. A single forgotten -latest in an evaluation script or a background job defeats the whole exercise, and it will be the one that produces the confusing result:

   rg -n -- '-latest' --glob '!node_modules' --glob '!*.lock'

Verify the pin

1. Check the model field on a live response and assert on it in a test that runs against the real API. A pin that is silently not in effect is worse than no pin, because you believe it:

   def test_model_is_pinned():
       resp = client.chat.complete(
           model=MODEL,
           messages=[{"role": "user", "content": "ping"}],
           max_tokens=1,
       )
       assert "-latest" not in MODEL, f"config still uses an alias: {MODEL}"
       assert resp.model == MODEL, f"asked {MODEL}, served {resp.model}"

2. Record the pinned id in whatever you log per request, alongside usage.prompt_tokens and usage.completion_tokens. When somebody asks in six weeks why the answers changed, the log tells you whether the model did.

Notice before it retires

This is the step that makes pinning safe rather than a way of storing up an outage. Mistral publishes retirement information per model, and the models endpoint exposes it, so a scheduled job can fail loudly while you still have time.

1. Write a check that fails when your pinned model is within a threshold of retirement or has vanished from the list entirely:

   import os, sys, json, datetime, urllib.request
   
   MODEL = os.environ["MISTRAL_MODEL"]
   WARN_DAYS = 60
   
   req = urllib.request.Request(
       "https://api.mistral.ai/v1/models",
       headers={"Authorization": f"Bearer {os.environ['MISTRAL_API_KEY']}"},
   )
   data = json.load(urllib.request.urlopen(req))["data"]
   entry = next((m for m in data if m["id"] == MODEL), None)
   
   if entry is None:
       sys.exit(f"FAIL: {MODEL} is no longer listed by the API")
   
   dep = entry.get("deprecation")
   if dep:
       left = (datetime.date.fromisoformat(dep[:10]) - datetime.date.today()).days
       if left < WARN_DAYS:
           sys.exit(f"FAIL: {MODEL} retires in {left} days ({dep})")
       print(f"ok: {MODEL} retires {dep} ({left} days)")
   else:
       print(f"ok: {MODEL} has no announced retirement date")

2. Run it on a schedule — nightly, or weekly in CI — rather than only on deploy. A service that has not deployed for two months is exactly the one that will be surprised.

3. When it warns, migrate deliberately: point a staging environment at the new snapshot, run your prompt suite against both, look specifically at output length, formatting habits and tool-calling eagerness, then move the pin. That is a half-day of work you scheduled, which is the entire point.