Where the REST API sits in the request path
The base host is api.cloudflare.com, with requests scoped to an account path under /client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/. That matters because gateway behaviour is not floating free of account context. The gateway choice sits inside the account, and Cloudflare can apply controls before the request reaches the model provider.
Four endpoint shapes are exposed through the AI REST API:
POST /ai/runfor universal model and modality accessPOST /ai/v1/chat/completionsfor OpenAI SDK compatibilityPOST /ai/v1/responsesfor OpenAI Responses API compatibilityPOST /ai/v1/messagesfor Anthropic SDK compatibility
The useful part is that compatibility does not force a separate control plane. An OpenAI-compatible client can point at the Cloudflare endpoint and keep its request shape. The same holds for Anthropic-style requests. Cloudflare keeps the gateway layer in the middle, which means logging and policy stay attached even when the client library changes.
api.cloudflare.com, account scoping, and gateway selection
Authentication uses Bearer $CLOUDFLARE_API_TOKEN with JSON payloads. The routing decision is tied to the account rather than to a single hard-coded upstream. If third-party model traffic arrives without extra routing detail, Cloudflare sends it through the account default gateway created on first use.
That default is convenient and slightly annoying. Convenient, because it removes setup friction. Annoying, because silent defaults are where traffic ends up when somebody assumes a specific gateway is already in play.
The cf-aig-gateway-id header overrides that default and sends the request through a chosen gateway. That is the clean control point when one account carries separate model paths, test traffic, or different policy sets.
OpenAI-compatible and Anthropic-compatible routes without changing the control plane
The endpoint compatibility is narrow in a useful way. OpenAI-style tools can use /ai/v1/chat/completions or /ai/v1/responses, while Anthropic-style clients use /ai/v1/messages. The model identifier still sits in the request, such as openai/gpt-5.5, but the gateway layer stays the same.
That keeps one operational shape across providers. The client library may speak OpenAI or Anthropic, but the request still lands in the same Cloudflare control path. No separate per-provider logging setup. No separate rate limiting layer stitched on later. Just one request path with different upstreams behind it.
How logging, rate limits, and guardrails are applied
Cloudflare attaches the gateway controls automatically. Logging, caching, rate limiting, and guardrails are not optional extras bolted on after the fact. They sit on the request path once AI Gateway handles the traffic.
That has a direct consequence: the controls follow the request, not the client’s idea of how the request should be handled. If the traffic passes through the gateway, the gateway can record it, shape it, and block it. The model provider still bills its own inference usage, but the gateway layer is where the policy becomes visible.
The automatic controls Cloudflare attaches to each request
Logging captures the request path through the gateway, which is what makes the rest of the control story usable. Rate limiting caps abuse and accidental bursts. Guardrails provide a policy boundary before the request gets to the provider. Caching sits beside those controls and avoids repeated calls where the response can be reused.
None of this is useful if the gateway path is bypassed. That is why the cf-aig-gateway-id header matters for third-party model traffic. It pins traffic to the right gateway instead of leaving it on whatever the account default happens to be.
For OpenAI-compatible and Anthropic-compatible routes, the main operational point is boring and important: compatibility does not remove the gateway layer. The request format changes, the enforcement point does not.
Unified Billing and the split between Gateway and model provider usage
Unified Billing separates the Cloudflare gateway usage from third-party model usage. That is the billing split that tends to matter during reviews and chargeback conversations. The gateway and the model provider are not one cost bucket pretending to be neat.
The practical consequence is simple. The request path can be unified while the bill is not. Cloudflare handles the gateway side, and the provider charges for the model side. If traffic moves across several providers, the billing model still keeps those layers apart.
Operational boundaries that catch people out
The default gateway behaviour is the part most likely to surprise someone skimming the docs and moving on. If cf-aig-gateway-id is omitted, third-party model requests route through the account default gateway created on first use. That is not a failure mode, but it is a place where traffic can land in the wrong policy context if the account contains more than one gateway.
Workers AI adds a separate wrinkle. The existing Workers AI REST path, /ai/run/@cf/{model}, still works. It does not disappear just because AI Gateway now sits on api.cloudflare.com. The catch is that AI Gateway use for Workers AI still needs the @cf/ model prefix, and if a gateway is involved the gateway choice still needs to be explicit.
Default gateway routing when cf-aig-gateway-id is omitted
Omitting cf-aig-gateway-id leaves third-party requests on the account default gateway. That is fine when there is one gateway and one policy path. It is awkward when there are several and the request was meant for a specific one.
The failure mode is dull, which is why it gets missed. Nothing breaks loudly. The request works. It just uses the wrong gateway. That can give the wrong logging trail, the wrong rate limit bucket, or the wrong guardrail set.
Keeping Workers AI on the @cf prefix while still using gateway controls
Workers AI still uses /ai/run/@cf/{model} for the existing REST path, and that prefix still matters. If AI Gateway is in the path, the request must keep the @cf/ model prefix and the gateway selection has to be set correctly.
That boundary matters because Workers AI is not treated like a generic third-party provider. The path stays, the prefix stays, and the gateway controls sit around it. In practice, that means avoiding the lazy habit of flattening every model request into one mental bucket. Cloudflare has not done that, and the API does not pretend otherwise.
Testing the controls against real traffic
Testing should start with one known request path and one known gateway, then move to rate-limited and guarded traffic. A basic OpenAI-compatible request against /ai/v1/chat/completions is enough to confirm the gateway path, logging, and provider routing. A second pass with cf-aig-gateway-id set checks that explicit gateway selection overrides the default.
For Anthropic-style requests, use /ai/v1/messages and confirm that the same account-scoped controls still apply. For Workers AI, keep the /ai/run/@cf/{model} path intact and verify that the gateway does not strip the model prefix on the way through.
A useful test is to send a small burst of requests and watch where rate limiting lands. Another is to check whether the log trail reflects the gateway you expected, not the account default. If the gateway ID is missing, the result may still look fine while sitting in the wrong place. That is the sort of thing that shows up later, usually when someone is staring at logs and muttering.
