支出アラート、ブロック、支出レポートは順次提供中です。有効になるまでは、ルールと設定は保存されますが、評価、ブロック、送信は行われません。
ルールの仕組み
ルールは次の要素で構成されます。- 指標: 何を測定するか（アラートの種類を参照）。
- スコープ: どの支出を数えるか。ワークスペース、1 つの API キー、1 つの部署などです。
- 期間: 暦日、暦週、暦月、または時間単位のローリングウィンドウ。
- しきい値: アラートを送信する金額またはパーセンテージ。
- アクション:
notify、または上限を超えたリクエストも拒否するblock。
アラートの種類とベース
パーセンテージはベース（
base_kind）に対して測定されます。
amount: ルールに設定した金額。アラートにのみ使用されます。workspace_budget: 対応する間隔のワークスペース予算（base_ref: 日の期間ならdaily、週ならweekly、月ならmonthly）。無期限の予算はベースにできません。key_limit: ルールの API キーに設定された、対応するウィンドウの支出上限。キーのスコープが必要です。previous_period: 前の期間の同じ時点までの支出（「昨日のこの時刻まで」など）。ローリングのルールでは直前のウィンドウ、予測では前の期間全体です。
スコープ
部署の支出はリクエストごとに割り当てられます。
- 部署に割り当てられたキーは、その部署にのみ数えられます。
- それ以外の場合は、キーの作成者で決まります。作成者の部署、または OAuth リクエストではサインインしたユーザーの部署です。
- 複数の部署に所属する人は、既定では すべて の部署に数えられます。ワークスペースの支出設定 で 所属するすべての部署 の代わりに 主な部署のみ を選択すると（API:
spend.department_attribution: "primary"）、主な部署だけに数えられます。主な部署が指定されていない場合は、手動で追加された部署が優先され、次に最も古い部署が使われます。
期間とタイムゾーン
日、週、月は暦の期間です。週は月曜日から日曜日までです。各ルールにはEurope/London や America/New_York のような IANA の time_zone を個別に設定できます。設定しない場合はワークスペースの請求タイムゾーンが使われ、既定は UTC です。請求タイムゾーンは ワークスペースの支出設定、または通知設定 API の spend.billing_time_zone で変更します。夏時間の切り替えも考慮され、タイムゾーン名は大文字と小文字が区別されます。
rolling の期間は直近の window_hours（1〜720）を対象とし、継続的に移動します。急増のルールはこれを急増のウィンドウとして、残高のルールは支出を平均する期間として使います。
キーの上限とワークスペースの予算は、常に UTC の区切りでリセットされます。別のタイムゾーンで
workspace_budget または key_limit をベースにしたルールは、自身のローカルの日、週、月をその上限と比較するため、上限が数える支出と異なる場合があります。しきい値と繰り返しのアラート
指標に応じて、ルールには 1〜5 個のパーセンテージのしきい値（1〜1000）か、1 つの金額のしきい値があります。- 暦の期間では、各しきい値が送信するアラートは期間ごとに最大 1 回です。複数のしきい値を同時に超えた場合は、最も高いしきい値を示す 1 件のアラートに、他のしきい値も記載されます。
- ローリング、急増、残高のルールは、代わりに
cooldown_minutes（5〜43,200、既定 360）を使います。クールダウン中は、より高いしきい値だけがアラートを送信します。クールダウン後も支出が上回っていれば、再びアラートが送信されます。 - この期間にすでに送信したしきい値は、ルールを編集しても再送信されません。
[TEST] と表示して、ルールの通知先に送ります。何も記録されず、ワークスペースは 1 分あたり 5 回までテストを送信できます。各ルールの 履歴 には、送信したアラートとブロックが表示されます。
リクエストのブロック
action: "block" を設定した spend または budget_percent のルールは、しきい値で警告し、支出がブロックポイントに達するとブロックします。ブロックポイントは、ベースの block_at_percent（既定 110、最も高いしきい値以上）、または spend ルールでは block_at_amount です。previous_period をベースにしたルールはブロックできません。最後のアラートとブロックポイントの間が猶予幅で、リクエストが止まる前にチームに警告が届きます。
ブロックが有効な間、スコープ内のリクエストには
spend_rule_blocked エラーコードとともに 429 が返されます。本文には reason: "spend_rule_block"、rule_id、rule_name、block_id、limit_scope、limit_value（USD）、reset_at が含まれます。Retry-After は期間がリセットされるまでの秒数です。ローリングのルールにはリセット時刻がありません。ブロックはウィンドウ内の支出がブロックポイントを下回るまで続き、レスポンスに Retry-After は含まれません。プロバイダーのブロックではそのプロバイダーのルートが除外され、他のルートが残っていない場合にのみリクエストが拒否されます。リアルタイムセッションはまだブロックされません。
支出がルールの最後のしきい値を超え、ブロックポイントには達していない間は、スコープ内のリクエストへのレスポンスに x-phaseo-spend-warning ヘッダーが付き、最大 3 件のルールが示されます（例: rule_id=…; scope=workspace; resets_at=2026-11-01T00:00:00.000Z）。クライアントはこれを記録したり、ブロックが始まる前にペースを落としたりできます。
ブロックは、期間がリセットされたとき、ローリングのルールの支出がブロックポイントを下回ったとき、またはルールが無効化、削除、変更されたときに自動で解除されます。オーナーと管理者は 支出アラート → 有効なブロック、または POST /v1/spend-blocks/{id}/lift で解除できます。解除したブロックは、同じ期間中（ローリングのルールでは 1 ウィンドウの間）は再開されません。支出ブロックの通知は、ブロックの開始時と解除時に送信されます。
残高と残り日数
balance ルールは、ワークスペースの利用可能残高（クレジット残高から、処理中のリクエストのために確保された金額を引いたもの）を監視します。ワークスペーススコープとローリングの期間を使い、次のいずれかの条件を満たすとアラートを送信します。
threshold_amount: 利用可能残高がこの金額以下になったとき。runway_days: 直近のwindow_hoursの 1 日あたり平均支出で、残高がこの日数より早く尽きるとき。最近の支出がなければ、残り日数のアラートは送信されません。
予測
forecast ルールは、現在の日、週、月の終わりまでの支出を直線的に予測します。これまでの支出を、期間のうち経過した割合で割った値です。静かな滑り出しでアラートが送信されないよう、日なら 3 時間、週なら 24 時間、月なら 72 時間が経過し、かつ 0.01 ドル以上が支出されるまで待機します。アラートには、現在のペースで上限に達する時期が記載されます。
金額の threshold_amount、またはベースとパーセンテージを設定します。previous_period をベースにした場合、予測は前の期間全体と比較されます。各しきい値のアラートは期間ごとに 1 回です。
急増
spike ルールは、直近の window_hours（1〜56）の支出を、その時間帯の通常の支出と比較します。
- 24 時間未満のウィンドウでは、通常の支出は過去 7 日間の各日の同じ時間帯の中央値です。それより長いウィンドウでは、過去 7 日間にある同じ長さの以前のウィンドウの中央値です。
- 支出が通常の
spike_multiplier倍（既定 3）以上で、かつspike_floor（既定 5 ドル）以上になるとアラートを送信します。 - 以前のウィンドウのうち少なくとも 3 つでワークスペースに支出がある必要があります。それまでは、エディターに学習中と表示されます。通常の支出が 0 の場合は、下限だけが適用されます。
- クールダウン（既定 6 時間）を使い、ブロックは行いません。
支出レポート
オーナーには既定で週次の支出レポートが届き、管理者はオプトインできます。日次と月次のレポートもあります。設定と内容はワークスペース通知のガイドで説明しています。そのほかの点は次のとおりです。- レポートは、期間の翌日の請求タイムゾーンで 09:00 から 21:00 の間に送信されます。その日に送信できなかった場合は、遅れて送信されずにスキップされます。
- レポートの予測は、現在の請求月が対象です。
- メンバーと部署の合計には非同期ジョブが含まれ、上記の部署のルールに従うため、全体の合計とわずかに異なる場合があります。
- 各ユーザーは、ワークスペースのレポートのうち自分宛てのものだけを配信停止できます。オーナーでも管理者でもないメンバーには送信されません。
ルーティングと通知先
支出ルールは 3 種類の通知を送信します。それぞれの送信先は 設定 → 通知 で選択します。
ルールには独自の通知先を設定できます。そのルールについては、支出アラートと支出ブロックのルートの代わりにそれらが使われます。すべて一時停止されている場合でも、ルールのアラートが代わりにルートへ送信されることはありません。アラートとブロックは、オーナーと管理者、およびルールの対象となるキーの作成者またはメンバーのモバイルアプリにも届きます。
カスタム Webhook は、
title、message、rule_id、rule_name、metric、scope、period、value_nanos、および指標に応じて base_nanos、forecast、spike、または残高のフィールドを含む JSON でアラートを受け取ります。各配信は署名で検証してください。ワークスペース通知の Webhook 署名の検証に関するセクションを参照してください。
API でルールを管理する
支出ルール API では、spend_rules:read、spend_rules:write、spend_rules:delete のいずれかを持つ管理キーを使います。金額はドル（threshold_amount_usd）でも、ナノドル単位の正確な値（threshold_amount_nanos）でも送信でき、レスポンスには両方が含まれます。
GET /v1/spend-rules/{id}/preview を、テストを送信するには POST /v1/spend-rules/{id}/test を使います。GET /v1/spend-blocks は有効なブロックを一覧表示します。請求タイムゾーン、部署への割り当て、レポートの設定は、通知設定の spend オブジェクトにあります。
Terraform でルールを管理する
Phaseo の Terraform プロバイダー（phaseoteam/phaseo）には、phaseo_spend_rule と phaseo_workspace_budget のリソース、および phaseo_spend_rules、phaseo_spend_blocks、phaseo_workspace_budgets のデータソースがあります。