Naming Conventions

Updated November 3, 2026. Based on the xAI Models page (Model Aliases section): the table includes grok-4.7, the model recommended by xAI, and grok-4.6. The production recommendation follows xAI’s guidance, which advises using the alias for most use cases and the dated version for workflows that require strict consistency. Source: Models.

Understand model identifiers

When you call the xAI API, the model field determines which model processes your request. xAI uses a structured naming system with aliases and pinned versions. Understanding this system is essential for managing the stability and migration of your applications.

The three identifier formats

xAI offers three ways to reference a model, each with distinct behavior:

Simple alias

{
  "model": "grok-4.20"
}

The simple alias points to the latest stable version of the model. When xAI releases a minor update, the alias automatically redirects to the new version. Your application always uses the most recent stable version without code changes.

Advantage: you automatically benefit from improvements. Risk: behavior may change slightly from one version to the next.

Latest alias

{
  "model": "grok-4.20-latest"
}

The latest alias points to the bleeding edge version—the very latest iteration, including versions not yet promoted to stable. This is the most recent but potentially the least tested version.

Advantage: immediate access to the latest improvements. Risk: behavior can change at any time; regressions are possible.

Pinned version

{
  "model": "grok-4.20-0309"
}

The pinned version identifies a specific model version, indexed by its release date (here, March 9). This version never changes: the behavior you observe today will be identical in six months.

Advantage: total stability, reproducible results. Risk: the version will eventually be deprecated and then removed.

Current full identifiers

Model lifecycle

Each xAI model follows a three-phase lifecycle:

1. Active — the model is available and recommended for production use
2. Deprecated — the model still works, but xAI recommends migrating to a newer version. A deadline is announced before removal
3. Obsolete — the model is removed. Requests to this model fail

Watch for deprecation announcements on the xAI console and in the release notes. When a model is deprecated, plan your migration without waiting for the removal date.

Recommendations by environment

Development

Use simple aliases (grok-4.7, grok-4.3) to automatically benefit from improvements. In development, a slight change in behavior between versions is acceptable and lets you spot incompatibilities before production.

Staging and testing

Use pinned versions (grok-4.20-0309-reasoning) to ensure test reproducibility. If a test passes today, it must pass tomorrow with exactly the same result.

Production

xAI recommends the simple alias or the -latest alias for most use cases, letting you automatically benefit from new features, and reserves the dated version for workflows that require strict consistency. If your production falls into this category—auditable results, compliance, regression testing—pin the dated version and plan periodic migrations after validation in staging.

Migration between versions

When you migrate from one version to another:

1. Update the model field in your requests
2. Test your existing prompts—newer models may respond differently
3. Check API parameters—a new version may support or deprecate certain parameters
4. Validate results—qualitatively compare outputs from the old and new versions

API endpoints

xAI maintains two main endpoints:

• /v1/responses — the main endpoint, recommended for all new projects
• /v1/chat/completions — the legacy endpoint, maintained for compatibility with existing clients

The legacy endpoint no longer receives new features. If you are starting a new project, use /v1/responses exclusively.

Key takeaways

• Three formats: simple alias (stable), latest alias (bleeding edge), pinned version (immutable)
• In production, use pinned versions for stability
• In development, use aliases to benefit from improvements
• Watch for deprecation announcements and plan your migrations
• The recommended endpoint is /v1/responses, not /v1/chat/completions
• Always test your prompts when migrating versions