> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# 支出アラート

> 支出、予算、予測、急増、残高不足のアラートを受け取り、支出が上限を超えたらリクエストをブロックします。

支出ルールはワークスペースの支出を監視し、しきい値を超えるとアラートを送信します。支出が猶予幅を超えたら、リクエストをブロックすることもできます。どのプランでも、ワークスペースあたり最大 50 件のルールを作成できます。

> [!NOTE]
>
> 支出アラート、ブロック、支出レポートは順次提供中です。有効になるまでは、ルールと設定は保存されますが、評価、ブロック、送信は行われません。

## ルールの仕組み

ルールは次の要素で構成されます。

* **指標**: 何を測定するか（[アラートの種類](#alert-types-and-bases)を参照）。
* **スコープ**: どの支出を数えるか。ワークスペース、1 つの API キー、1 つの部署などです。
* **期間**: 暦日、暦週、暦月、または時間単位のローリングウィンドウ。
* **しきい値**: アラートを送信する金額またはパーセンテージ。
* **アクション**: `notify`、または上限を超えたリクエストも拒否する `block`。

Phaseo は、リクエストの完了から数分後に、記録された使用量からルールを評価します。ルールのあるワークスペースは 1 時間ごとにも確認され、残高のルールは 15 分ごとに確認されます。支出には動画、バッチ、音楽、リアルタイムのジョブも含まれます。

ルールを作成するには、**Gateway → 設定 → 通知 → 支出アラート** を開き、**アラートを追加** を選択します。エディターには保存済みルールの現在の値が表示され、テストアラートを送信できます。API キーのページと予算のページには、キーの上限または予算をベースにしてエディターを開くショートカットがあります。メンバーはルールを閲覧でき、オーナーと管理者はルールの作成、変更、テスト、削除ができます。

## アラートの種類とベース

| 指標 | アラートを送信する条件 | 期間 |
| - | - | - |
| `spend` | 期間中の支出が `threshold_amount` に達したとき | すべて |
| `budget_percent` | 支出がベースの一定割合に達したとき。50、80、100 のように最大 5 つのしきい値を設定可能 | すべて |
| `forecast` | 期間末までの予測支出が金額、またはベースの一定割合に達したとき | 日、週、月 |
| `spike` | 直近数時間の支出が通常の支出の数倍になったとき | ローリング |
| `balance` | 利用可能残高が一定額まで下がったとき、または残りの日数が一定未満になったとき | ローリング、ワークスペーススコープのみ |

パーセンテージはベース（`base_kind`）に対して測定されます。

* `amount`: ルールに設定した金額。アラートにのみ使用されます。
* `workspace_budget`: 対応する間隔のワークスペース予算（`base_ref`: 日の期間なら `daily`、週なら `weekly`、月なら `monthly`）。無期限の予算はベースにできません。
* `key_limit`: ルールの API キーに設定された、対応するウィンドウの支出上限。キーのスコープが必要です。
* `previous_period`: 前の期間の同じ時点までの支出（「昨日のこの時刻まで」など）。ローリングのルールでは直前のウィンドウ、予測では前の期間全体です。

削除された予算や支出上限のないキーなど、ベースがないルールは、ベースが再び存在するまで何も送信しません。ガードレールには支出上限がないため、ベースにはできません。

## スコープ

| スコープ | `scope_id` | 数える対象 |
| - | - | - |
| `workspace` | なし | ワークスペースのすべての支出 |
| `key` | API キーの ID | そのキーで行われたリクエスト |
| `member` | メンバーのユーザー ID | メンバーが作成したキーで行われたリクエストと、メンバー自身の OAuth リクエスト |
| `department` | 部署の ID | 部署に所属する人が行ったすべて（下記を参照） |
| `model` | `openai/gpt-5` のようなモデル ID | そのモデルが処理したリクエスト |
| `provider` | プロバイダー ID | そのプロバイダーが処理したリクエスト |

部署の支出はリクエストごとに割り当てられます。

1. 部署に割り当てられたキーは、その部署にのみ数えられます。
2. それ以外の場合は、キーの作成者で決まります。作成者の部署、または OAuth リクエストではサインインしたユーザーの部署です。
3. 複数の部署に所属する人は、既定では **すべて** の部署に数えられます。**ワークスペースの支出設定** で **所属するすべての部署** の代わりに **主な部署のみ** を選択すると（API: `spend.department_attribution: "primary"`）、主な部署だけに数えられます。主な部署が指定されていない場合は、手動で追加された部署が優先され、次に最も古い部署が使われます。

部署の所属はルールを評価するたびに読み取られます。そのため、ある人を別の部署に移すと、現在の期間の支出も一緒に移ります。1 人が複数の部署に数えられることがあるため、部署の合計がワークスペースの合計を上回る場合があります。2026 年 9 月より前の使用量は、メンバーや部署に割り当てられていません。

## 期間とタイムゾーン

日、週、月は暦の期間です。週は月曜日から日曜日までです。各ルールには `Europe/London` や `America/New_York` のような IANA の `time_zone` を個別に設定できます。設定しない場合はワークスペースの請求タイムゾーンが使われ、既定は UTC です。請求タイムゾーンは **ワークスペースの支出設定**、または[通知設定 API](https://phaseo.app/docs/ja/v1/api-reference/endpoint/notifications-settings-update.md) の `spend.billing_time_zone` で変更します。夏時間の切り替えも考慮され、タイムゾーン名は大文字と小文字が区別されます。

`rolling` の期間は直近の `window_hours`（1〜720）を対象とし、継続的に移動します。急増のルールはこれを急増のウィンドウとして、残高のルールは支出を平均する期間として使います。

> [!NOTE]
>
> [キーの上限](https://phaseo.app/docs/ja/v1/api-reference/limits.md#key-limits-and-budgets)と[ワークスペースの予算](https://phaseo.app/docs/ja/v1/api-reference/endpoint/budgets-list.md)は、常に 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` をベースにしたルールはブロックできません。最後のアラートとブロックポイントの間が猶予幅で、リクエストが止まる前にチームに警告が届きます。

> [!WARNING]
>
> ブロックはベストエフォートです。記録された使用量に基づくため、ブロックは支出がブロックポイントを超えてから数分後に始まり、その間に支出がブロックポイントを超えることがあります。すべてのリクエストで確認される厳密な上限には、キーの上限またはワークスペースの予算を使ってください。

| | 支出ルールによるブロック | キーの上限 | ワークスペースの予算 |
| - | - | - | - |
| 確認のタイミング | 数分ごと、記録された使用量から | リクエストごと | リクエストごと |
| スコープ | ワークスペース、キー、メンバー、部署、モデル、プロバイダー | 1 つのキー | ワークスペース |
| 期間 | 任意のタイムゾーンの日、週、月、またはローリング | UTC の日、週、月 | UTC の日、週、月、または無期限 |
| 無料モデル | `block_free_models` が true でない限りブロックされない | 数えられる | 数えられる |
| 事前の警告 | あり（ルールのしきい値で） | なし | なし |
| 解除 | オーナーまたは管理者が、期間の残りについて解除 | 上限を引き上げる | 予算を引き上げる |

ブロックが有効な間、スコープ内のリクエストには `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`](../api-reference/endpoint/spend-blocks-lift.mdx) で解除できます。解除したブロックは、同じ期間中（ローリングのルールでは 1 ウィンドウの間）は再開されません。支出ブロックの通知は、ブロックの開始時と解除時に送信されます。

## 残高と残り日数

`balance` ルールは、ワークスペースの利用可能残高（クレジット残高から、処理中のリクエストのために確保された金額を引いたもの）を監視します。ワークスペーススコープとローリングの期間を使い、次のいずれかの条件を満たすとアラートを送信します。

* `threshold_amount`: 利用可能残高がこの金額以下になったとき。
* `runway_days`: 直近の `window_hours` の 1 日あたり平均支出で、残高がこの日数より早く尽きるとき。最近の支出がなければ、残り日数のアラートは送信されません。

残高のルールは、残高が下がるたびに 1 回アラートを送信します。残高が回復してから再び下がった場合にのみ再送信され、クールダウンより頻繁には送信されません。自動チャージが有効で正常に機能している間は、アラートは送信されません。

**設定 → クレジット** の残高不足メールは、シンプルな既定の機能として残ります。残高がしきい値を下回るたびに 1 回、最大で 6 時間に 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 時間）を使い、ブロックは行いません。

比較は正確に 24 時間刻みで行われるため、夏時間の切り替え後は、現地時刻で 1 時間前または後の時間帯と比較されます。急増のルールは、新しい使用量が届いたときに確認されます。

## 支出レポート

オーナーには既定で週次の支出レポートが届き、管理者はオプトインできます。日次と月次のレポートもあります。設定と内容は[ワークスペース通知のガイド](https://phaseo.app/docs/ja/v1/guides/workspace-notifications.md#spend-reports)で説明しています。そのほかの点は次のとおりです。

* レポートは、期間の翌日の請求タイムゾーンで 09:00 から 21:00 の間に送信されます。その日に送信できなかった場合は、遅れて送信されずにスキップされます。
* レポートの予測は、現在の請求月が対象です。
* メンバーと部署の合計には非同期ジョブが含まれ、上記の部署のルールに従うため、全体の合計とわずかに異なる場合があります。
* 各ユーザーは、ワークスペースのレポートのうち自分宛てのものだけを配信停止できます。オーナーでも管理者でもないメンバーには送信されません。

## ルーティングと通知先

支出ルールは 3 種類の通知を送信します。それぞれの送信先は **設定 → 通知** で選択します。

| ルート | 種類 | 送信されるタイミング |
| - | - | - |
| 支出アラート | `spend_alert` | ルールのしきい値を超えたとき |
| 支出ブロック | `spend_blocked` | ブロックが開始または解除されたとき（`payload.state` は `started` または `lifted`） |
| 支出レポート | `spend_report` | 支出レポートの送信時期になったとき |

ルールには独自の通知先を設定できます。そのルールについては、支出アラートと支出ブロックのルートの代わりにそれらが使われます。すべて一時停止されている場合でも、ルールのアラートが代わりにルートへ送信されることはありません。アラートとブロックは、オーナーと管理者、およびルールの対象となるキーの作成者またはメンバーのモバイルアプリにも届きます。

カスタム Webhook は、`title`、`message`、`rule_id`、`rule_name`、`metric`、`scope`、`period`、`value_nanos`、および指標に応じて `base_nanos`、`forecast`、`spike`、または残高のフィールドを含む JSON でアラートを受け取ります。各配信は署名で検証してください。[ワークスペース通知](https://phaseo.app/docs/ja/v1/guides/workspace-notifications.md)の Webhook 署名の検証に関するセクションを参照してください。

## API でルールを管理する

[支出ルール API](https://phaseo.app/docs/ja/v1/api-reference/endpoint/spend-rules-list.md) では、`spend_rules:read`、`spend_rules:write`、`spend_rules:delete` のいずれかを持つ管理キーを使います。金額はドル（`threshold_amount_usd`）でも、ナノドル単位の正確な値（`threshold_amount_nanos`）でも送信でき、レスポンスには両方が含まれます。

```bash theme={null}
curl https://api.phaseo.app/v1/spend-rules \
  -H "Authorization: Bearer $PHASEO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly budget",
    "metric": "budget_percent",
    "period": "month",
    "base_kind": "workspace_budget",
    "base_ref": "monthly",
    "threshold_percents": [50, 80, 100],
    "action": "block",
    "block_at_percent": 110
  }'
```

現在の値と次のしきい値を確認するには [`GET /v1/spend-rules/{id}/preview`](../api-reference/endpoint/spend-rules-preview.mdx) を、テストを送信するには [`POST /v1/spend-rules/{id}/test`](../api-reference/endpoint/spend-rules-test.mdx) を使います。[`GET /v1/spend-blocks`](../api-reference/endpoint/spend-blocks-list.mdx) は有効なブロックを一覧表示します。請求タイムゾーン、部署への割り当て、レポートの設定は、[通知設定](https://phaseo.app/docs/ja/v1/api-reference/endpoint/notifications-settings-update.md)の `spend` オブジェクトにあります。

## Terraform でルールを管理する

[Phaseo の Terraform プロバイダー](https://github.com/phaseoteam/terraform-provider-phaseo)（`phaseoteam/phaseo`）には、`phaseo_spend_rule` と `phaseo_workspace_budget` のリソース、および `phaseo_spend_rules`、`phaseo_spend_blocks`、`phaseo_workspace_budgets` のデータソースがあります。

```hcl theme={null}
resource "phaseo_workspace_budget" "monthly" {
  interval = "monthly"
  limit    = 500
}

resource "phaseo_spend_rule" "monthly_budget" {
  name               = "Monthly budget"
  metric             = "budget_percent"
  period             = "month"
  base_kind          = "workspace_budget"
  base_ref           = "monthly"
  threshold_percents = [50, 80, 100]
  action             = "block"
  block_at_percent   = 110

  depends_on = [phaseo_workspace_budget.monthly]
}

resource "phaseo_spend_rule" "spike" {
  name             = "Spend spike"
  metric           = "spike"
  period           = "rolling"
  window_hours     = 3
  spike_multiplier = 4
}
```

既存のルールや予算は ID でインポートします。

```bash theme={null}
terraform import phaseo_spend_rule.monthly_budget 11111111-1111-4111-8111-111111111111
```

エージェント向けの支出ルールに関するルール（このページの要約）:

* 支出ルールのブロックはベストエフォートで、上限の数分後に始まります。正確な上限には、キーの上限またはワークスペースの予算を使ってください。
* ブロックされたリクエストは、`spend_rule_blocked`、`rule_id`、`block_id`、`reset_at` とともに `429` を返します。`Retry-After` まで待ってください。これがない場合、ブロックはローリングウィンドウの支出が下がるか、オーナーまたは管理者が `POST /v1/spend-blocks/{id}/lift` で解除するまで続きます。ループで再試行しないでください。
* レスポンスの `x-phaseo-spend-warning` は、ブロックするルールが最後のアラートのしきい値を超えたことを示します。ブロックが続く可能性があります。
* ルールで `block_free_models` を設定しない限り、無料モデルはブロックされません。
* 暦の期間はルールのタイムゾーンを使います（既定はワークスペースの請求タイムゾーンで、その既定は UTC）。キーの上限とワークスペースの予算は UTC を使います。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.