Cloudflare AI Gateway adds model aliases: call a pool of models by one name, with failover (November 4, 2026)

What you get

On November 4, 2026 Cloudflare added model aliases to AI Gateway. An alias is a pool of models your app calls by one name, such as custom/support-fast. The gateway either tries the models in the order you set and falls back to the next one when a request fails, or uses smart routing to pick a model for each request. Your code only names the alias, so you can swap models or change the routing without redeploying.

Aliases belong to one gateway. You manage them on the gateway's Routing page, next to dynamic routes.
Up to 100 aliases per gateway, and 1 to 50 models per alias. An alias can't point to another custom/ alias.
Fallbacks can't get around authentication, billing or gateway policies.

Prerequisites

A Cloudflare account ID in CLOUDFLARE_ACCOUNT_ID
A Cloudflare API token with Workers AI > Read permission in CLOUDFLARE_API_TOKEN
An AI Gateway with authentication turned on and an alias set up on its Routing page
Unified Billing, or stored provider keys, for the models in the alias

Steps

In the dashboard, open your gateway, go to Routing and create an alias with the models you want, in order.
Call it through the REST API: send the alias as model and name the gateway in the cf-aig-gateway-id header:

Shell

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-gateway-id: my-gateway" \
  --data '{
    "model": "custom/support-fast",
    "input": {
      "messages": [
        { "role": "user", "content": "Reply with a short greeting." }
      ]
    }
  }'

Test it

Run the request with your own gateway and alias names. You should get a short greeting back. Change the alias's model order on the Routing page and run it again without touching the code.

Not confirmed

Neither the changelog nor the docs page states a price for aliases.