Model routing
Cloudflare AI Gateway: model aliases and fallback
AI Gateway model aliases arrived on November 4. Organize models and fallback without redeploying while preserving format, permission and cost controls.
In this article
An alias separates the application from model ordering. It does not make formats interchangeable or guarantee savings or uptime: test each destination and the failure path.
What model aliases change#
On November 4, 2026, Cloudflare added model aliases to AI Gateway. An application requests a custom/ name and the gateway resolves its pool of destinations. Configuration can change without an application redeploy, although propagation can temporarily retain cached configuration.
Documentation: Cloudflare · Model aliases, 4 November 2026
Choose routing and prepare destinations#
preferred tries eligible models in configured order; smart selects a model per request and uses the default order when it cannot rank them. Request options can override the saved preference. Enable authentication and configure Unified Billing or provider keys before testing.
| Test | What it establishes |
|---|---|
| Primary responds | The request format is compatible with that destination. |
| Primary fails | An eligible alternative responds while respecting policies. |
| Structured output | The schema remains valid when the alternative responds. |
| Workflow cost | Attempts, tokens and tools are counted, not just the final response. |
Documentation: Cloudflare · AI Gateway model aliases
A test request body#
{
"model": "custom/support-fast",
"input": {
"messages": [
{
"role": "user",
"content": "Return one short greeting."
}
]
},
"options": {
"routing": {
"algorithm": "preferred"
}
}
}Documentation: Cloudflare · AI Gateway model aliases
Roll out the change with control#
- Start with a staging alias and models that support your application’s request contract.
- Simulate a recoverable failure and a permission failure. Confirm which allows fallback and what the user sees.
- Record effective model, configuration version and cost per task without storing sensitive prompt data in logs.
- Roll out gradually and retain a way to restore the previous order. Renaming the alias also changes the name the application must request.
Compare total cost and completed-task rate against your own criteria. An alias is not a quality measurement and does not enable unsupported models or formats.