When you call the Claude API, what goes in the model parameter? And how does an ID like claude-opus-4-8 differ from a short name like opus? This guide covers model IDs and versioning on the API. (For performance/use comparison by model family, see the model comparison; for SDK install and first call, the SDK guide. This sits in between: how to choose and manage the string.) As of June 2026, source: Claude official docs.
Every model ID is a "pinned snapshot"
Per the official docs, every Claude model ID is a pinned snapshot. IDs with a date (e.g. ...20250929) are fixed to that specific release. As long as you use the same ID, you get the same model weights.
Dateless IDs are pinned too (a common misconception)
From the Claude 4.6 generation, model IDs use a dateless format (e.g. claude-opus-4-8, claude-sonnet-4-6). A common misconception is that a dateless ID like claude-sonnet-4-6 always routes to the latest/best version. It does not. From 4.6 on, the dateless ID is the canonical ID for that release and a single fixed snapshot. Anthropic does not change the weights or config of an existing ID; updated versions always ship under a new ID.
Model weights are fixed for an ID, but the serving infrastructure around it (request router, safety classifiers, sampling logic) can change over time, and occasionally observable behavior shifts slightly even when the ID and weights are unchanged (official docs).
Aliases are "convenience pointers" (they can change)
Aliases are different. For example, opus resolves to the recommended Opus version and sonnet to the recommended Sonnet version. (For pre-4.6 models, the Claude API alias column was a convenience pointer resolving to the most recent dated snapshot for that minor version.) What an alias points to changes over time. Convenient — but in production it means the model can change under you with no code change, shifting behavior.
Pin the version in production
So the recommended pattern is clear: aliases are handy for dev, testing, and one-off scripts; for production and reproducibility, pin the full model ID.
# Pin: full model ID — always the same snapshot
message = client.messages.create(
model="claude-opus-4-8", # pinned snapshot
max_tokens=1024,
messages=[{"role": "user", "content": "Hi"}],
)
# alias: convenience pointer — resolves to the recommended version (can change over time)
message = client.messages.create(
model="opus", # dev / testing
max_tokens=1024,
messages=[{"role": "user", "content": "Hi"}],
)Plan for updates and deprecation
Every model ID (dated or dateless) has its own distinct deprecation and retirement schedule. A pinned ID keeps behavior stable, but when that model is slated for retirement you'll need to migrate to a new ID. For teams, record the switch date, model version, and any prompt adjustments so you can diagnose behavior changes later. Check schedules in the official models overview and deprecation docs.
Query the Models API
Which models are available, and their context/output limits, can be queried in code via the Models API. Instead of maintaining a hardcoded table, query at runtime and it's always current.
# Query available models, capabilities, and token limits in code
models = client.models.list() # the list
m = client.models.retrieve("claude-opus-4-8")
m.id # "claude-opus-4-8"
m.display_name # "Claude Opus 4.8"
m.max_input_tokens # context window (int)
m.max_tokens # max output tokens (int)Summary
Key points: (1) every model ID is a pinned snapshot; (2) from 4.6 on, dateless IDs are pinned too (not auto-latest); (3) aliases (opus, sonnet, etc.) are convenience pointers that can change; (4) pin the full ID in production; (5) updates ship as new IDs, so plan for deprecation/migration; (6) use the Models API to query available models and limits in code.
Model ID lists, alias mappings, and availability can differ by date and deployment (Claude API, AWS, Vertex, Foundry). Always confirm the latest IDs and deprecation schedules in the official model docs before shipping to production.