Spend limits（利用上限）では、AI Gateway にコストベースの予算を設定できます。時間ウィンドウ内の累計支出が上限に達すると、ウィンドウがリセットされるまで、AI Gateway は以降のリクエストを 429 レスポンスでブロックします。
レート制限 はリクエスト数を制限します。一方、Spend limits はモデルの料金に基づくリクエストあたりの実コスト（ドル）を追跡します。制限の対象は、モデル、プロバイダー、ユーザー ID・チーム・アプリケーションなどの カスタムメタデータ ディメンションを、任意に組み合わせてスコープできます。
Spend limits は、料金が既知のモデルについて、Unified Billing のリクエストと BYOK のリクエストの両方に適用されます。
各 Spend limit ルールは、ローリングまたは固定の時間ウィンドウに対する予算（ドル）を定義します。AI Gateway はトークン使用量とモデル料金から各リクエストのコストを算出し、上限に対する累計支出をリアルタイムで追跡します。
プロバイダーへリクエストを送る前に、AI Gateway は適用されるすべての Spend limit ルールを一度に評価します。いずれかのルールが予算超過なら、リクエストは 429 レスポンスでブロックされます。
Spend limits は eventual consistency です。現在のリクエストのコストは完了後に記録されます。そのため、同時リクエストのバーストでは、適用が追いつくまでの短い間、上限を超えることがあります。
各ルールは、次の 1 つ以上のディメンションでスコープできます。
- Limit by provider — リクエストで使ったプロバイダーです。
- Limit by model — リクエストで使ったモデルです。
- Limit by metadata — リクエストに付ける カスタムメタデータ のキーです。メタデータキー名を入力します（例:
agent_idやenvironment）。
各ディメンションは、次の 2 つのモードのいずれかで設定できます。
| モード | 動作 | 例 |
|---|---|---|
| Split by value | 値ごとに独立した予算バケットを持ちます。 | たとえば agent_id を渡すと、agent_id で分割した場合、エージェントごとに独自の予算になります。 |
| Filter by value | ディメンションが特定の値と一致するときだけルールが適用されます。 | たとえば agent_id を渡して agent_id を agent_42 にフィルターすると、そのエージェントのリクエストだけが対象になります。 |
ルールにディメンションを設定しない場合、すべての値が 1 つの予算バケットを共有します。たとえば provider ディメンションのないルールは、すべてのプロバイダーの支出をまとめて追跡します。
モデルが openai/gpt-5.5 で、agent_id メタデータの値が agent_42 のリクエストを考えます。
| シナリオ | ディメンション | 予算バケット |
|---|---|---|
| 全員共通のグローバル予算 | なし | 共有バケット 1 つ |
| エージェントごとの予算 | agent_id メタデータ: 値で分割 |
エージェントごとに別バケット |
| プロバイダーごと、エージェントごと | agent_id メタデータ: 値で分割、provider: 値で分割 |
エージェントとプロバイダーの組み合わせごとに別バケット |
| 特定モデルのみ | model: 値でフィルター openai/gpt-5.5 |
openai/gpt-5.5 のリクエストだけに適用 |
| エージェントごと、モデルごと | agent_id メタデータ: 値で分割、model: 値で分割 |
エージェントとモデルの組み合わせごとに別バケット |
Spend limits は、ゲートウェイごとにダッシュボードまたは API で設定します。ダッシュボードでは、ゲートウェイを選択して Settings > Spend limits を開きます。ゲートウェイあたり最大 20 件のルールを定義できます。
ユーザー ID やチームなどのカスタムディメンションで Spend limits をスコープするには、リクエストに カスタムメタデータ を付けます。
ルールをユーザー識別子でスコープすると、ユーザーごとに独自の予算を持てます。識別子の取得方法は、ゲートウェイの認証方法によって異なります。
ゲートウェイが Cloudflare Access で保護されている場合、AI Gateway は認証済み Access ユーザー ID を、予約済みの cf.user_id メタデータキーとして各リクエストに自動追加します。クライアントアプリケーションからユーザー ID を渡す必要はありません。
ユーザーごとの予算を設定するには、次の手順を実行します。
- Cloudflare ダッシュボード ↗ で AI > AI Gateway を開き、ゲートウェイを選択します。
- Settings > Spend limits を開き、ルールを追加します。
- Limit by metadata で Add metadata dimension を選択し、キーに
cf.user_idを入力します。 - ディメンションを Split by value に設定します。
- 予算額と時間ウィンドウを設定し、保存します。
認証済みの Access ユーザーごとに、独立した予算が割り当てられます。特定のユーザーだけを制限するには、ディメンションを Filter by value にし、そのユーザーの Access JWT sub クレームを入力します。
ゲートウェイが Access の背後にない場合は、独自のユーザー識別子を カスタムメタデータ として渡します（例: user_id キー）。次に Limit by metadata で、キー user_id のディメンションを追加し、Split by value に設定します。
Spend limit を超えると、AI Gateway は 429 Too Many Requests を返します。次の 2 つの選択肢があります。
- リクエストをブロックする（デフォルト） - 予算ウィンドウがリセットされるまで、リクエストは拒否されます。
- より安価なモデルへフォールバックする - プライマリモデルとフォールバックを持つ Dynamic Route を作成します（例:
anthropic/claude-opus-4.7のフォールバックを@cf/moonshotai/kimi-k2.6にする）。次に、この機能でプライマリモデルに Spend limit を設定します。プライマリモデルの予算を超えると、AI Gateway はブロックせず、自動でフォールバックモデルへリクエストを振り分けます。
モデル、プロバイダー、任意のカスタムメタデータ属性ごとの支出は、Analytics ダッシュボード で追跡できます。利用傾向を把握し、根拠のある予算を設定するために使います。
- コスト追跡は、トークン数とモデル料金に基づく最善努力の見積もりです。正確な請求額は、各プロバイダーのダッシュボードを参照してください。
- ゲートウェイあたり設定できる Spend limit ルールは最大 20 件です。