Cloudflare AI Gateway Custom Costs: 2026 Deep Dive

Why a Cost Number You Can Override Matters

Every AI gateway dashboard has the same quiet flaw: the dollar figure in the top-right corner comes from a public price list, not from your contract. If your team negotiated $1 per million input tokens on a model whose list price is $2.50, the gateway tool that "tracks your AI spend" is overstating it by 150 percent. Finance sees one number, procurement signed a different one, and the only way to reconcile is a spreadsheet someone maintains by hand.

Cloudflare's fix is a single request header. cf-aig-custom-cost lets you override the default or public model cost that AI Gateway attributes to a call, per request, with your real negotiated rates. On September 9, 2026, Cloudflare extended it: the changelog entry titled "AI Gateway custom costs support cache tokens" added per_cache_read_token and per_cache_write_token to the header. That turns a blunt input/output override into a cost model that can actually represent prompt caching — which is the dominant cost variable for any agent workload running on Anthropic or OpenAI models in 2026.

This is a narrow feature with an outsized effect on one specific job: making a gateway's own cost telemetry trustworthy enough to be the source of truth. It is worth understanding exactly what it does, what the cache-token math is, and where Cloudflare sits relative to the two competitors that ship something comparable.

The Header, Property by Property

Custom costs apply at the request level, not per account or per key. You attach the header to the same call you would normally make through the gateway:

curl https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai/chat/completions \
  --header "Authorization: Bearer $CLOUDFLARE_UPSTREAM_KEY" \
  --header 'Content-Type: application/json' \
  --header 'cf-aig-custom-cost: {"per_token_in":0.000001,"per_token_out":0.000002,"per_cache_read_token":0.0000001,"per_cache_write_token":0.0000005}' \
  --data '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Summarize this changelog entry."}]
  }'

The four supported properties are per_token_in, per_token_out, per_cache_read_token, and per_cache_write_token. One detail trips people up on first read: every value is a cost per single token, not per million tokens. The docs note there is no limit on decimal places, which is why the example above uses 0.000001 to express "$1 per million input tokens." The same example maps to $1 input, $2 output, $0.10 cache-read, and $0.50 cache-write per million.

Two operational constraints matter as much as the syntax. First, custom costs only apply to requests that pass tokens in their response; a request with no token information gets no cost calculated at all, so streaming endpoints that omit usage blocks will silently stay uncosted. Second, when the pricing is applied you can see it: Cloudflare underlines custom-cost figures in the request logs specifically so you can tell at a glance which entries used your negotiated rates versus the public list.

The Cache-Token Math, With the Worked Example

The interesting engineering in the September 9 update is not the two new fields — it is how Cloudflare reconciles providers that report cache usage differently. The docs put it plainly: some providers include cache-read and cache-write tokens within the input token count, while others report input and cache tokens as separate counts.

AI Gateway normalizes both. When cache tokens are included in the input count, it subtracts them before applying per_token_in. When they are reported separately, it applies their cost in addition to the input cost. The stated goal is to prevent cache tokens from being double-counted.

The documented example: a response reports 1,000 input tokens, 600 cache-read tokens, 200 cache-write tokens, and 100 output tokens. AI Gateway computes 1,000 - 600 - 200 = 200 fresh input tokens, then applies each custom rate to its corresponding token count. If you had set a cache-read rate of $0.10 per million and a cache-write rate of $0.50 per million, you would be billed for 200 input tokens at the input rate, 600 at the cache-read rate, 200 at the cache-write rate, and 100 output tokens at the output rate — not 1,000 input tokens plus cache tokens on top.

Activation is deliberately forgiving. Cache-token pricing is optional and turns on if you specify at least one cache rate. If you specify only one of the two, the other defaults to per_token_in. If you omit both, AI Gateway ignores cache-token counts entirely and falls back to its existing input/output calculation — your old configuration keeps working unchanged.

One edge case is worth internalizing before you rely on the numbers in production: a cache hit always costs 0, even with a custom cost set. Custom costs only apply when the request reaches the model provider. That is the behavior you want, but it also means a validation run against a cache-warm gateway can look like the header did nothing at all.

What This Actually Saves You: A Negotiated-Rate Walkthrough

Take a realistic scenario. A team routes 40 million input tokens and 12 million output tokens per month through Cloudflare AI Gateway to a frontier model, and separately runs an agent workload with heavy prompt caching: 30 million cache-read tokens and 4 million cache-write tokens per month. Procurement negotiated $1.00 per million input, $2.00 per million output, $0.10 per million cache-read, and $0.50 per million cache-write — while the model's public list price is $2.50 input and $15.00 output.

Without the header, AI Gateway's cost analytics compute from list price: 40M input at $2.50 plus 12M output at $15.00, and cache tokens folded into the input count at list rate. The dashboard reports roughly $100 in input and $180 in output before cache — a figure that has no relationship to the invoice. Spend limits built on that number fire early and block legitimate traffic, alerts for anomaly detection trip on phantom cost, and the cost-per-request metric each engineering team sees is inflated by whatever the list-versus-contract spread happens to be.

With the header set once and applied to the calling path, the same traffic reports $40 of input, $24 of output, $3 of cache-read, and $2 of cache-write. That is a 3.4x difference in the headline number — and it is the difference between a telemetry system you can trust and one you have to mentally discount every time you read it. The header does not change what you pay the model provider; it changes whether the gateway's own accounting matches the invoice.

How Cloudflare Compares to the Other Gateways

Cloudflare is not the only gateway with a cost-override story, but the field is smaller than it looks. We checked the official pricing and documentation pages for the six gateways an apirank reader is most likely to be choosing between. Only two document a user-set override comparable to cf-aig-custom-cost.

The pattern is worth naming. Portkey approaches the problem from the observability side: it gives you per-model cost overrides and a multiplier that can represent a negotiated discount on an entire integration, which is the right shape when your discounts are contract-level rather than model-level. LiteLLM approaches it from the self-hosted-proxy side and is the most granular of the three — custom pricing maps, a percentage discount per provider, and a margin config designed for internal chargeback, so you can model both what you pay and what you charge back. Cloudflare's version is the narrowest and the most operationally light: one header, no config state, available on every plan including free, with the cache-token normalization handled for you.

That narrowness is the point. If you are already routing through Cloudflare AI Gateway — for the edge caching, the 235-model catalog, or the Workers integration — then a header on the request path is a materially lower-friction way to fix cost telemetry than standing up a Portkey or LiteLLM instance whose primary job is cost attribution. Conversely, if negotiated-rate accounting is the core requirement and you need per-provider discounts or chargeback margins as first-class config, Cloudflare's single header is not a replacement for LiteLLM.

Implementing It Without Breaking Your Existing Setup

The rollout is deliberately boring, which is a feature. The header is additive — omit it and AI Gateway behaves exactly as before. That means you can pilot on a single calling path and compare the gateway's cost figure against a known invoice line before touching anything else.

Two practical notes from the docs that change how you should test. First, because custom costs only apply when tokens are returned in the response, verify your client and model combination actually surfaces usage data before concluding the header is broken. Second, because cache hits always cost 0, a test against a warm cache proves nothing — either disable caching on the gateway for the test, or use a unique prompt that cannot be a cache hit.

For teams running multiple models with different negotiated rates, the header is set per request, which means the rate has to travel with the call. That is more moving parts than a config-level override, and it is the honest trade-off: Cloudflare gives you the capability without giving you a central place to declare a rate card. If your rate card is small and stable, a small wrapper in your client that attaches the header by model ID solves it in an afternoon. If you have dozens of models under dozens of contracts, you will want that wrapper to read from a config file rather than hardcoding rates in call sites — and at that volume, LiteLLM's config-first model starts to look less like overhead and more like the right shape.

The Verdict

Custom costs are a small feature that fixes a specific, real problem: gateway cost telemetry that disagrees with the invoice. The September 9 extension to cache tokens matters more than it sounds, because prompt caching is where the list-versus-contract gap compounds fastest — a cache-heavy agent workload can have 70 percent of its input tokens billed at a cache rate, and a cost model that prices them as fresh input is not slightly wrong, it is directionally wrong about where the spend lives.

Cloudflare's execution is right for its position in the market. It is available on every plan including free, it handles the inclusive-versus-separate provider reporting divergence automatically rather than pushing that parsing onto you, and it is one header rather than a configuration surface. What it does not give you — a central rate-card declaration, per-provider discount multipliers, chargeback margins — is exactly what LiteLLM already does well, and Portkey covers the middle ground with contract-level multipliers. If your gateway choice was already made on other grounds, this feature removes the main reason to run a second tool just for cost attribution. If cost attribution is your primary reason for running a gateway at all, the comparison table above is the decision, not this one feature.

Frequently Asked Questions

Do I need an Enterprise plan to use cf-aig-custom-cost? No. Cloudflare states AI Gateway is available on all plans, and the custom-cost documentation does not gate the feature. The gateway itself includes 10 million requests per month, then $0.05 per additional million, with core analytics, caching, and rate limiting free.

Can I set a custom cost for a model Cloudflare does not natively support? Yes, and the docs' own example uses a non-Cloudflare provider endpoint (OpenAI). AI Gateway's separate Custom Providers feature lets you route to any HTTPS API endpoint, and custom costs apply at the request layer rather than being tied to a specific first-party model.

What happens if I set only one cache rate? The unspecified one defaults to per_token_in. If you omit both cache rates, AI Gateway ignores cache-token counts entirely and preserves your existing input/output calculation — so adding the cache fields is opt-in and reversible.

Why is my custom cost showing zero on some requests? Most likely the response is being served from edge cache, in which case Cloudflare states the cost is always 0 regardless of custom cost settings. The other possibility is that the response did not include token usage data, since custom costs only apply to requests that pass tokens in their response.

How do I confirm the custom cost actually applied? Cloudflare underlines custom-cost figures in the request logs, which makes it possible to distinguish entries that used your negotiated rates from entries priced at public list rates without cross-referencing a separate dashboard.