Claude API Model IDs and Versioning: Aliases, Pinned Snapshots, and Migration

When you call the Claude API, what goes in the model parameter? And how does an ID like claude-opus-5 differ from an alias like claude-haiku-4-5? 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 September 2026 (re-checked against the model-ids-and-versions and models overview docs), source: Claude official docs.

Update (September 27, 2026): Claude Opus 5.5 was released on September 22, 2026 and is now the current Opus model (API claude-opus-5-5, $4 per million input tokens and $20 per million output tokens, down from Opus 5's $5/$25). Anthropic says it performs at the level of Fable 5.1 on most work and costs 40% less to run than Opus 5 on typical workloads. Opus 5 remains available but is marked legacy in the official model docs. Opus 5 prices and comparisons below reflect the pre-launch state and will be updated. Details: Claude Opus 5.5 complete guide.

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-5, 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. Per the official docs, Claude API aliases exist only for models before the 4.6 generation: a dateless name such as claude-sonnet-4-5 or claude-haiku-4-5 is a convenience pointer that resolves to the most recent dated snapshot for that minor version (e.g. claude-haiku-4-5-20251001). From the 4.6 generation on, the dateless ID (claude-opus-5, etc.) is the snapshot, so there is no separate alias. (One-word names like opus or sonnet are Claude Code /model shortcuts, not valid API model values.) What an alias points to changes when a new dated snapshot ships. 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-5",   # 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="claude-haiku-4-5",  # alias (pre-4.6 generation) — 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-5")
m.id                 # "claude-opus-5"
m.display_name       # "Claude Opus 5"
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 (claude-haiku-4-5 etc., pre-4.6 generation only) 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.

Learn more: for how much one request can handle and how to manage tokens, see the context windows and tokens guide.

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.

See also: Claude Model Comparison Guide

Related articles

• Claude Model Comparison: Opus 5, Sonnet 5, Haiku 4.5, Fable 5
• Claude API Context Windows and Tokens: Limits and Management
• Getting Started with the Claude API: Your First Call (Developer Intro)
• Claude API Keys: Getting a Key, Pricing & Usage (2026)
• Claude API Tool Use Guide: How Function Calling Works