Unified Billing

Unified Billing allows users to connect to various AI providers (such as OpenAI, Anthropic, and Google AI Studio) and receive a single Cloudflare bill. To use Unified Billing, you must purchase and load credits into your Cloudflare account in the Cloudflare dashboard, which you can then spend with AI Gateway.

Pre-requisites

• Ensure your Cloudflare account has sufficient credits loaded.
• Ensure you have authenticated your AI Gateway.

Load credits

To load credits for AI Gateway:

1. In the Cloudflare dashboard, go to the AI Gateway page.

   Go to AI Gateway

   The Credits Available card on the top right shows how many AI gateway credits you have on your account currently.

2. In Credits Available, select Manage.

3. If your account does not have an available payment method, AI Gateway will prompt you to add a payment method to purchase credits. Add a payment method.

4. Select Top-up credits.

5. Add the amount of credits you want to purchase, then select Confirm and pay.

Auto-top up

You can configure AI Gateway to automatically replenish your credits when they fall below a certain threshold. To configure auto top-up:

1. In the Cloudflare dashboard, go to the AI Gateway page.

   Go to AI Gateway

2. In Credits Available, select Manage.

3. Select Setup auto top-up credits.

4. Choose a threshold and a recharge amount for auto top-up.

When your balance falls below the set threshold, AI Gateway will automatically apply the auto top-up amount to your account.

Use Unified Billing

Unified Billing works in two ways: through the AI binding or through the HTTP API. Both deduct credits from your account automatically without requiring provider API keys.

Note

Workers AI models (models prefixed with @cf/) routed through AI Gateway are not charged via Unified Billing. These models are billed through Workers AI pricing instead. Unified Billing only applies to third-party provider models (such as OpenAI, Anthropic, and Google AI Studio).

AI binding

Call any model listed in the model catalog using env.AI.run(). This includes both Workers AI models and third-party models from providers like OpenAI, Anthropic, and Google.

TypeScript

const resp = await env.AI.run(
  "openai/gpt-4.1-mini",
  {
    messages: [{ role: "user", content: "What is Cloudflare?" }],
  },
  {
    gateway: { id: "my-gateway" },
  },
);

Refer to the binding reference for the full API surface.

HTTP API

Call a supported provider through the AI Gateway REST API without passing a provider API key. Use the cf-aig-authorization header to authenticate with your Cloudflare API token.

curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/default/compat/chat/completions \
  --header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "google-ai-studio/gemini-2.5-pro",
    "messages": [
      {
        "role": "user",
        "content": "What is Cloudflare?"
      }
    ]
  }'

Explain Code

The default gateway is created automatically on your first request. Replace default with a specific gateway ID if you have already created one.

The HTTP API supports the following providers through provider-native endpoints and the Unified API (chat completions):

• OpenAI
• Anthropic
• Google AI Studio
• Google Vertex AI
• xAI
• Groq

Spend limits

Set spend limits to prevent unexpected charges on your loaded credits. You can define daily, weekly, or monthly limits. When a limit is reached, the AI Gateway automatically stops processing requests until the period resets or you increase the limit.

Zero Data Retention (ZDR)

Zero Data Retention (ZDR) routes Unified Billing traffic through provider endpoints that do not retain prompts or responses. Enable it with the gateway-level zdr setting, which maps to ZDR-capable upstream provider configurations. This setting only applies to Unified Billing requests that use Cloudflare-managed credentials. It does not apply to BYOK or other AI Gateway requests.

ZDR does not control AI Gateway logging. To disable request/response logging in AI Gateway, update the logging settings separately in Logging.

ZDR is currently supported for:

• OpenAI
• Anthropic

If ZDR is enabled for a provider that does not support it, AI Gateway falls back to the standard (non-ZDR) Unified Billing configuration.

Default configuration

Dashboard

To set ZDR as the default for Unified Billing in the dashboard:

1. Log into the Cloudflare dashboard ↗ and select your account.
2. Go to AI > AI Gateway.
3. Select your gateway.
4. Go to Settings and toggle Zero Data Retention (ZDR).

API

To set ZDR as the default for Unified Billing using the API:

1. Create an API token with the following permissions:
   • AI Gateway - Read
   • AI Gateway - Edit
2. Get your Account ID.
3. Send a PUT request to update the gateway and include zdr: true or zdr: false in the request body.

Per-request override (cf-aig-zdr)

Use the cf-aig-zdr header to override the gateway default for a single Unified Billing request. Set it to true to force ZDR, or false to disable ZDR for the request.

Unified Billing request with ZDR

curl -X POST https://gateway.ai.cloudflare.com/v1/$CLOUDFLARE_ACCOUNT_ID/{gateway_id}/openai/chat/completions \
  --header "cf-aig-authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-zdr: true' \
  --data '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Explain Zero Data Retention."
      }
    ]
  }'

Explain Code