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

# 予算

> エンタープライズの予算による ACU上限のツリー構成、月次期間と予算ごとのユーザーティアの設定、API を使った予算の管理方法について説明します。

予算を利用すると、会社の組織構造に合わせて ACU 使用量に上限を設定できます。アカウント全体に 1 つの上限を設け、チームやプロジェクトごとに共有プールを用意し、さらに各プール内でユーザーごとの上限を設定できます。

## ユースケースの例

### 部門管理者への委任

Acme Corp には 10 の部門があります。各部門長は自部門の組織の上限を管理し、各部門の合計は中央 IT が設定します。この例では、そのうち 2 つの部門を取り上げます。

エンタープライズ管理者の Alice は、Account 予算の下に部門ごとの予算を作成し、それぞれを各部門の管理者と共有します。各部門の管理者は、自部門の組織ごとに予算を作成します。

![100,000 ACU の Account 予算と、その下にある 30,000 ACU の Engineering（Payments と Search を含む）および 5,000 ACU の Marketing。](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/budget-departments.svg?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=fd65b7ebd17f98f03e694dae32493b69)

Account 予算の下にある部門予算

* Engineering 部門の管理者である Bob は、Engineering 配下のどの予算にも上限と一時的な上限を設定できます。たとえば、繁忙期の 1 週間だけ Payments に 6,000 ACU の一時的な上限を設定できます。
* Bob は Engineering の上限である 30,000 ACU を引き上げることはできません。引き上げられるのは Alice だけです。
* 各組織の予算の合計が 30,000 ACU を超えていても、Engineering 配下のすべての組織の使用量は 30,000 ACU の上限に算入されます。

![部門管理者として表示した予算ページ](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/dept-admin-tree.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=9f921d3d02cf54e6a28792beb1db26b5)

部門管理者として表示した予算ページ（Account 予算はロックされています）

![子予算の上限の引き上げ](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/dept-admin-edit-child.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=a12442bc7a00464d08283bad62358864)

部門管理者が子予算の上限を引き上げる様子

![部門予算の上限は read-only です](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/dept-admin-own-limit.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=7fc6e5bf029581de28e3290e6beb7554)

部門管理者は部門予算の上限を変更できません

### ユーザー上限を引き上げたプロジェクト用の予算枠

すべての開発者には月 200 ACU が割り当てられています。移行プロジェクトのために、Acme Corp は 5,000 ACU を確保し、プロジェクトのメンバーがより多く利用できるようにします。

Developer tools の組織は、200 ACU のデフォルトティアを持つ Developer tools 予算に置いたままにします。上限 5,000 ACU の Migration initiative 予算を作成してプロジェクトの組織を配置し、1,000 ACU のデフォルトティアを設定します。どちらの予算も Account 予算の配下に置かれます。

![Developer tools は 20,000 ACU で 200 ACU のデフォルトティア、Migration initiative は 5,000 ACU で 1,000 ACU のデフォルトティア。](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/budget-project.svg?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=a0d7477384a985d998a72ef8ae73f481)

Developer tools 予算と Migration initiative 予算、およびそれぞれのティア

* プロジェクトの開発者である Carol は、Migration 組織では最大 1,000 ACU、Developer tools の組織では最大 200 ACU を利用できます。
* プロジェクト全体での利用量は、1 か月あたり 5,000 ACU を超えることはありません。

![「自分の利用状況分析」の予算ピッカー](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/my-analytics-multi-budget.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=1b91652d38ed08edbcba1468f074af59)

複数の予算が表示された「自分の利用状況分析」の予算ピッカー

## 予算の仕組み

### 予算ツリー

各エンタープライズアカウントには予算ツリーが1つあります。ルートは **Account 予算** で、その下に子予算が配置されます。ツリーは最大3階層まで作成できます。

1つの予算には、1つまたは複数の組織を含めることができます。各組織が属する予算は必ず1つです。新しい組織は Account 予算 の下に配置されます。

たとえば、Acme Corp が Account 予算 に 100,000 ACU の上限を設定し、Engineering がそのプールを3つの子予算に分割するとします。

![100,000 ACU の Account budget。その下に 40,000 ACU の Engineering とその3つの子予算、および3つのユーザー上限ティアを持つ 20,000 ACU の Developer tools。](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/budget-tree.svg?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=48dc89ce8cd22e3043b576e5349ce1e0)

予算とユーザー上限ティアを含む予算ツリー

ティアは1つの予算内で設定するユーザーごとの上限であり、独立した予算ではありません。

![予算ごとの使用率を示す予算ツリー](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/tree.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=cc09209e5169718deadade894b7b4802)

予算ごとの使用率を示す予算ツリー（モックデータ）

### 予算の上限

予算の上限は、その予算に属する組織と、子予算に属する組織の ACU 使用量の合計を、月次期間ごとに制限します。上限が `null` の場合は無制限です。

* **使用量はすべての祖先予算に計上されます。** 子予算での使用量は、その親予算と Account 予算にも計上されます。
* **祖先予算が上限に達すると、その子予算での使用も阻止されます。** 経路上のいずれかの予算が上限に達すると、そのブランチでの使用は停止します。
* **子予算の上限の合計は、親予算の上限を超えてもかまいません。** その場合でも、合計使用量は親予算の上限によって制限されます。
* **上限のない予算も、親予算の上限によって制限されます。**

1 つの組織のみにリンクされた予算は、その組織と上限を共有します。この上限は、非推奨の [organization-level ACU 上限エンドポイント](https://docs.devin.ai/ja/admin/billing/org-acu-limits#organization-endpoints) でも設定できます。後述の [更新エンドポイント](#update-a-budget) を利用することもできます。

### 予算を使い切った場合

予算を使い切ると、その予算に属する組織では利用が停止されます。いずれかの親予算を使い切った場合も同様に停止されます。利用は次の月次期間に再開されます。また、管理者が上限を引き上げるか、一時的な上限を設定した場合にも再開されます。

* **Devin セッション:** 新しいセッションを開始できなくなり、実行中のセッションはスリープ状態になります。ユーザーには「Increase your organization's usage limit.」と表示されます。
* **Devin CLI およびデスクトップのローカルエージェント:** リクエストはブロックされます。ユーザーには「Your organization has reached its monthly usage limit. Ask an account admin to raise it, or wait for the limit to reset next month.」と表示されます。
* **Devin Review:** 新しいレビューはブロックされます。

![コンポーザーのバナー: 使用量の上限に到達](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/cloud-limit-reached.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=419babb34f9e136d7cd10853b3d18074)

予算を使い切ったときに表示されるコンポーザーのバナー

### 月次期間

予算の上限、ユーザーの上限、一時的な上限は、各月次期間の開始時にリセットされます。各期間は請求フェーズの開始日から始まるため、必ずしも暦月とは一致しません。

たとえば、請求フェーズが15日に始まる場合、期間は10月15日〜11月14日、その次は11月15日〜12月14日となります。

**一時的な上限**は、現在の期間の残りの間、予算の上限に代わって適用されます。次の期間には恒久的な上限に戻ります。一時的なユーザーオーバーライドは、現在の期間の終了時に失効します。

![一時的な上限が設定された Marketing の予算](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/limits-temporary.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=f5394365ee93dd0a9107ec8d650e8a93)

一時的な上限により、この期間に限り Marketing の上限を 6,000 ACU に引き上げた例

### 予算内のユーザー上限

ユーザー上限は、1 人のユーザーが月次期間内に使用できる量の上限です。組織がリンクされた予算はそれぞれ独自のユーザー上限を持ち、その上限は当該予算内でのみ適用されます。

* **ティア。** 各予算には独自のティアと、1 つのデフォルトティアがあります。ティアでは、そのメンバーの月間 ACU 上限を設定します。
* **IdPグループマッピング。** アイデンティティプロバイダーのグループをティアに関連付けます。グループのメンバーには、そのティアが適用されます。
* **上書き設定。** 特定のユーザーに対して、恒久的または一時的な上限を設定します。
* **リクエストポリシー。** 上限引き上げリクエストの処理方法はティアごとに設定します。`unconditional` と `conditional` では、ティアの `max_limit` までのリクエストが承認されます。`manual` では、リクエストが管理者に送られてレビューされます。
* **スコープ。** ユーザー上限の対象となるのは、その予算に属する組織でのユーザーの使用量のみです。
* **コピーとクリア。** 別の予算またはアカウントからティアをコピーできます。IdPグループマッピング、割り当て、上書き設定もコピーできます。予算内のティアをすべてクリアして、一から設定し直すこともできます。

> [!WARNING]
>
> 親予算のユーザー上限は、その子予算には適用されません。たとえば、Engineering 自体も組織を持っている場合、Engineering に設定した 300 ACU のユーザー上限によって、Payments や Search でのユーザーの使用量が制限されることはありません。

![使用量ポリシーのコピーダイアログ](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/copy-policies.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=bafda52c62081f5c5d3d71266eff8cad)

ソースとして Developer tools を選択した、使用量ポリシーのコピーダイアログ

### 予算を管理できるユーザー

Enterprise 管理者は、**エンタープライズ設定** の **予算** で予算を管理します。Account 予算を含め、ツリー全体を管理できます。

* **委任。** エンタープライズ管理者は、Manage access タブで予算をユーザーまたはグループと共有できます。委任された管理者は、その予算の配下に予算を作成し、それらの子予算に上限と一時的な上限を設定できます。委任機能は別途有効化が必要です。アカウント担当チームまでお問い合わせください。
* **委任された管理者は、共有された予算自体の上限を引き上げることはできません。** この上限を変更できるのは、親予算を管理する管理者のみです。
* **メンバー** は、**自分の利用状況分析** で自分の使用量と上限を確認できます。

![Engineering 予算の Manage access タブ](https://mintcdn.com/cognitionai/_lCZXv8Jkk2Nq1kL/images/admin/budgets/dept-admin-access.png?fit=max\&auto=format\&n=_lCZXv8Jkk2Nq1kL\&q=85\&s=a90c02116678e594ff6dfef6511b6724)

Engineering 予算の Manage access タブ（Bob をマネージャーとして設定した例）

## よくある質問

> [accordion] 組織管理者は組織の ACU 上限を設定できますか？
>
> いいえ。組織の ACU 上限を設定するのは Enterprise 管理者です。チームが自身の上限を管理できるようにするには、そのチームの管理者と予算を共有してください。

> [accordion] 組織上限エンドポイントが 409 を返すのはなぜですか？
>
> お客様の企業で予算の上限が強制適用されている場合、組織が他の組織と予算を共有しているとき、または組織が Account 予算の直下にあるときは、組織上限エンドポイントは HTTP `409` を返します。エラーメッセージは「This organization has no limit of its own. Set the limit on its budget.」です。たとえば、Globex、Initech、Umbrella が 1 つの予算を共有している場合、Globex の上限を書き込もうとすると `409` が返されます。

> [accordion] 上限はいつリセットされますか？
>
> 各月次期間の開始時にリセットされます。月次期間は、請求フェーズの開始日から始まります。

> [accordion] 1 つの組織を 2 つの予算に含めることはできますか？
>
> いいえ。各組織が属する予算は必ず 1 つだけです。一方、1 つの予算には複数の組織を含めることができます。

## V3 API で予算を管理する

すべてのリクエストは、エンタープライズの**サービスユーザートークン**で認証します。呼び出し元には、アカウントの **ManageAcuLimits** 権限、またはその予算への[委任されたアクセス](#who-can-manage-a-budget)が必要です。ベース URL には `https://api.devin.ai` を使用します。認証およびサービスユーザーに関するガイダンスについては、[V3 API の概要](https://docs.devin.ai/ja/api-reference/v3/overview.md)を参照してください。

予算スコープのコレクションエンドポイントでは、パスで予算を指定します：`/v3beta1/enterprise/usage-policies/budgets/{budget_id}/...`。単一のティアまたはリクエストを対象とするエンドポイント (`/tiers/{tier_id}`、`/requests/{request_id}`) は、そのティアまたはリクエストから予算を特定するため、アカウント全体のエンドポイントと同じパスを使用します。

### PATCH のセマンティクス

`PATCH` エンドポイントでは、各フィールドは次のように処理されます。

* 省略したフィールドは変更されません。
* `null` を指定したフィールドはクリアされます。
* 値を指定したフィールドは作成または更新されます。

## 予算関連のエンドポイント

### 予算の一覧を取得

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets
```

アカウントの予算 (アクティブなものと archive 済みのものの両方) をページ分割されたリストとして返します。各予算の形式は次のとおりです:

```json theme={null}
{
  "budget_id": "budget-abc123",
  "name": "Engineering",
  "parent_budget_id": "budget-root",
  "org_ids": ["org-xyz789"],
  "status": "active",
  "cycle_acu_limit": 2000,
  "temporary_cycle_acu_limit": null
}
```

* `budget_id`: 予算スコープのパスで使用する識別子。
* `parent_budget_id`: 親予算。アカウントのルート予算の場合は `null`。
* `org_ids`: この予算にリンクされている組織。これらの組織の使用量はこの予算に計上されます。リンクされている組織がない場合は空になります。
* `status`: `active` または `archived`。
* `cycle_acu_limit`: 月次請求期間ごとに、この予算とその子孫予算に対して課金される ACU消費量の上限。`null` は無制限を表します。
* `temporary_cycle_acu_limit`: 現在の月次請求期間が終了するまで `cycle_acu_limit` を上書きする上限。有効な上限がない場合は `null`。

### 予算を更新する

```http theme={null}
PATCH /v3beta1/enterprise/usage-policies/budgets/{budget_id}
```

部分更新です。省略したフィールドは変更されず、`null` を指定すると上限がクリアされます。少なくとも 1 つのフィールドを指定する必要があります。

* `parent_budget_id`: 予算をそのサブ予算ごと、別のアクティブな予算の配下に移動します。ルート予算は移動できません。また、予算のネストは最大 3 階層までです。
* `cycle_acu_limit`、`temporary_cycle_acu_limit`: 予算の上限です (一覧取得のレスポンスと同じ形式) 。

**リクエストボディ — 上限と今月の一時的な引き上げを設定する**

```json theme={null}
{
  "cycle_acu_limit": 2000,
  "temporary_cycle_acu_limit": 2500
}
```

**リクエストボディ — 上限を解除する**

```json theme={null}
{
  "cycle_acu_limit": null,
  "temporary_cycle_acu_limit": null
}
```

**リクエストボディ — 予算を別の予算の配下に移動する場合**

```json theme={null}
{
  "parent_budget_id": "budget-platform"
}
```

更新後の予算を返します。`temporary_cycle_acu_limit` を再度設定すると、現在のウィンドウで改めて適用し直されます。1 つの組織のみにリンクされた予算の場合、`cycle_acu_limit` はその組織のACU上限としても適用されます。

## ティアのエンドポイント

### ティアの一覧

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/tiers
```

予算のティアを優先順位順に並べた、ページ分割されたリストを返します。`priority` が最も高いものから順に並び、同じ `priority` 内では新しいティアが先になります。各ティアの形式は次のとおりです:

```json theme={null}
{
  "tier_id": "tier-abc123",
  "name": "Engineers",
  "is_default": true,
  "cycle_acu_limit": 500,
  "policy": "manual",
  "max_limit": null,
  "priority": 0,
  "member_count": 42,
  "created_at": 1735689600
}
```

* `is_default`: このティアが予算のデフォルトティアかどうか。
* `cycle_acu_limit`: 各メンバーに適用される、サイクルごとのデフォルトのACU上限。`null` は上限がないことを示します。
* `policy`: このティアに対する上限引き上げリクエストの処理方法。`unconditional` と `conditional` は `max_limit` まで承認し、`manual` は管理者によるレビューが必要です。
* `max_limit`: 引き上げリクエストを承認できる上限の最大値。`null` の場合は上限なしで承認されます。`cycle_acu_limit` が `null` の場合は常に `null` になります。
* `priority`: ユーザーのIdPグループにマッピングされた階層の中で、このティアの優先順位を決める値。値が最も大きいティアが優先され、同値の場合は最も新しいティアが優先されます。ユーザーへの明示的な割り当てはこの順位付けより優先されます。また、デフォルトティアは順位付けの対象外です。
* `member_count`: 現在このティアに属しているユーザー数。デフォルトティアの場合は、他のティアに属していないすべての予算メンバーを数えます。

### ティアを作成する

```http theme={null}
POST /v3beta1/enterprise/usage-policies/budgets/{budget_id}/tiers
```

**リクエストボディ**

```json theme={null}
{
  "name": "Engineers",
  "cycle_acu_limit": 500,
  "policy": "manual"
}
```

予算の最初のティアは、自動的にその予算のデフォルトティアになります。HTTP `201` と、作成されたティアを返します。

### ティアを取得する

```http theme={null}
GET /v3beta1/enterprise/usage-policies/tiers/{tier_id}
```

### ティアを更新する

```http theme={null}
PATCH /v3beta1/enterprise/usage-policies/tiers/{tier_id}
```

部分更新です。省略したフィールドは変更されません。

```json theme={null}
{
  "name": "Engineering",
  "cycle_acu_limit": 750
}
```

### ティアを削除する

```http theme={null}
DELETE /v3beta1/enterprise/usage-policies/tiers/{tier_id}
```

成功すると HTTP `204` を返します。デフォルトティアは削除できません (先に別のティアをデフォルトに昇格させてください) 。ユーザーが所属しているティアを削除する場合は、事前にそのユーザーを別のティアに移動し、そのティアへの IdPグループマッピングもすべて削除しておく必要があります。

## ティアユーザーのエンドポイント

### ティアのユーザー一覧を取得する

```http theme={null}
GET /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users
```

ティアに属するユーザーを、決定された上限とあわせてページ分割されたリストで返します。デフォルトティアの場合は、他のティアに属していないすべての予算メンバーが対象です:

```json theme={null}
{
  "user_id": "user_abc123",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "cycle_acu_limit_override": null,
  "temporary_cycle_acu_limit": 800,
  "effective_cycle_acu_limit": 800,
  "limit_source": "temporary_override",
  "membership": "explicit"
}
```

* `cycle_acu_limit_override`: ユーザーの永続的なオーバーライド (設定されている場合) 。
* `temporary_cycle_acu_limit`: ユーザーの一時的なオーバーライド。現在の月次請求期間内で有効な場合にのみ含まれます。
* `effective_cycle_acu_limit`: ユーザーに現在強制適用されている上限。`null` は上限がないことを示します。
* `limit_source`: 実効上限の適用元。`override` (永続) 、`temporary_override`、`tier` のいずれかです。
* `membership`: ユーザーがそのティアに属している理由。`explicit` (直接割り当て) 、`idp_group` (優先される IdPグループマッピング経由) 、`default` (デフォルトティアへのフォールバック) のいずれかです。

### ユーザーをティアに割り当てる

```http theme={null}
PUT /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users/{user_id}
```

冪等です。成功時には HTTP `204` を返します。別のティアからユーザーを移動すると、ユーザーごとの上書き設定はすべてクリアされ、ユーザーには移動先ティアの上限がそのまま継承されます。

### ティアからユーザーを削除する

```http theme={null}
DELETE /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users/{user_id}
```

ユーザーに対する明示的なティアの割り当て (および上書き設定) を削除します。削除後、そのユーザーにはIdPグループにマッピングされた階層があればそれが適用され、なければデフォルトティアが適用されます。成功時には HTTP `204` を返します。

## ユーザーエンドポイント

### ユーザーの上限を取得する

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/users/{user_id}
```

予算内でのユーザーの決定されたティア、上限、および保留中のリクエストを返します。上記の[ティアのユーザーフィールド](#list-a-tiers-users)に加えて、次のフィールドが含まれます。

```json theme={null}
{
  "tier_id": "tier-abc123",
  "tier_name": "Engineers",
  "tier_cycle_acu_limit": 500,
  "pending_request_id": null,
  "pending_request_cycle_acu_limit": null
}
```

* `tier_id` / `tier_name`: ユーザーの上限の決定元となるティア (明示的な割り当て、IdPグループマッピング、またはデフォルトティア) 。予算にティアがない場合は `null` になります。
* `tier_cycle_acu_limit`: 上書き設定を適用する前の、ティア自体の上限。`null` の場合は上限がないことを意味します。
* `pending_request_id` / `pending_request_cycle_acu_limit`: ユーザーの保留中の上限引き上げリクエストと、そのリクエストで要求している上限 (存在する場合) 。

### ユーザーの上書き設定を指定またはクリアする

```http theme={null}
PATCH /v3beta1/enterprise/usage-policies/budgets/{budget_id}/users/{user_id}
```

User-scoped：対象ユーザーが予算のメンバーであれば十分で、ティアは関係しません。また、ユーザーのティア割り当てが変更されることもありません。

**リクエストボディ — 一時的なオーバーライドを設定する**

```json theme={null}
{
  "cycle_acu_limit": 800,
  "kind": "temporary"
}
```

値を設定する場合は `kind` が必須です。`permanent` は無期限で、`temporary` は現在の月次請求期間の終了時に失効します。

**リクエストボディ — すべての上書き設定をクリアする**

```json theme={null}
{
  "cycle_acu_limit": null
}
```

成功すると、このエンドポイントは HTTP `204` を返します。

## IdP グループのエンドポイント

IdP グループをティアに関連付けると、そのグループのメンバーにティアが自動的に継承されます。マッピングはグループメンバーシップに基づいてリアルタイムで決定され、ユーザーに明示的に割り当てられたティアが変更されることはありません。明示的な割り当てが常に優先されます。複数のマッピング済みグループに属するユーザーには、最上位のマッピング済みティア (ティアの `priority` が最も高いもの。同順位の場合は最も新しいティア) が適用されます。

### IdPグループマッピングの一覧を取得

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups
```

予算のグループとティアのマッピングを、ページ分割されたリストとして古い順に返します。`?tier_id=` でフィルターすると、特定の 1 つのティアに関連付けられたグループのみを一覧表示できます:

```json theme={null}
{
  "idp_group_id": "grp_abc123",
  "idp_group_name": "Engineering",
  "tier_id": "tier-abc123"
}
```

### IdP グループのマッピングを取得する

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups/{idp_group_name}
```

予算内にグループのマッピングが存在しない場合は、HTTP `404` を返します。

### IdPグループをティアにマッピングする

```http theme={null}
PUT /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups/{idp_group_name}
```

**リクエストボディ**

```json theme={null}
{
  "tier_id": "tier-abc123"
}
```

冪等なアップサートです。ティアは対象の予算に属している必要があります。1 つのグループを関連付けられるティアは予算ごとに最大 1 つまでのため、すでに関連付け済みのグループを関連付けると、そのグループは指定したティアに移動します。

### IdP グループの関連付けを解除する

```http theme={null}
DELETE /v3beta1/enterprise/usage-policies/budgets/{budget_id}/idp-groups/{idp_group_name}
```

成功すると HTTP `204` を返します。マッピング済みティアは、そのグループのメンバーに適用されなくなります。明示的な割り当てがなく、他のマッピング済みティアも適用されないユーザーには、デフォルトティアが適用されます。

## 上限引き上げリクエストのエンドポイント

ユーザーは、サイクルごとの上限の引き上げをリクエストできます。リクエストの処理方法は、リクエスト者のティアの `policy` によって決まります。`unconditional` と `conditional` の場合はティアの `max_limit` まで自動的に承認され、`manual` の場合はリクエストが保留され、管理者がこれらのエンドポイントを使ってレビューします。

### 上限引き上げリクエストの一覧

```http theme={null}
GET /v3beta1/enterprise/usage-policies/budgets/{budget_id}/requests
```

予算に対する申請の一覧をページ分割して返します。`?status=` (`pending`、`approved`、`denied`、`expired`) および `?user_id=` でフィルターできます。

```json theme={null}
{
  "request_id": 42,
  "user_id": "user_abc123",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "tier_id": "tier-abc123",
  "tier_name": "Engineers",
  "current_cycle_acu_limit": 500,
  "requested_cycle_acu_limit": 800,
  "message": "Wrapping up a large migration this month",
  "status": "pending",
  "created_at": 1735689600,
  "reviewed_at": null,
  "reviewer": null
}
```

* `tier_id` / `tier_name`: 予算内でのリクエスト者のティア。予算にティアがない場合は `null` になります。
* `current_cycle_acu_limit`: リクエスト者に現在適用されている上限。`null` の場合は上限がないことを示します。
* `status`: `expired` は、請求サイクルの終了時点でリクエストがまだ保留中だったことを示します。
* `reviewer`: リクエストをレビューした管理者。保留中は `null` になります。

### 上限引き上げリクエストを取得する

```http theme={null}
GET /v3beta1/enterprise/usage-policies/requests/{request_id}
```

### 上限引き上げリクエストを承認する

```http theme={null}
POST /v3beta1/enterprise/usage-policies/requests/{request_id}/approve
```

リクエストされた上限を、現在の月次請求期間の終了時に失効する**一時的なオーバーライド**として付与します。必要に応じて、別の上限を付与することもできます。

```json theme={null}
{
  "cycle_acu_limit": 700
}
```

更新後のリクエストを返します。リクエストがすでにレビュー済みの場合、またはリクエスト元のユーザーがアカウントメンバーではなくなっている場合は、HTTP `409` を返します。

### 上限引き上げリクエストを拒否する

```http theme={null}
POST /v3beta1/enterprise/usage-policies/requests/{request_id}/deny
```

更新後のリクエストを返します。リクエストがすでにレビュー済みの場合は、HTTP `409` を返します。

## ワークフローの例

### 予算のティアを設定する

対象の予算を特定して月 2,000 ACU の上限を設定し、デフォルトティアを作成して、予算のすべてのメンバーに月 500 ACU の上限を適用します。

```bash theme={null}
curl "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets" \
  -H "Authorization: Bearer <token>"

curl -X PATCH "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cycle_acu_limit": 2000}'

curl -X POST "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123/tiers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standard", "cycle_acu_limit": 500, "policy": "manual"}'
```

IdP グループをティアに関連付け、特定のユーザー 1 人の上限を今月末まで一時的に引き上げます:

```bash theme={null}
curl -X PUT "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123/idp-groups/Engineering" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tier_id": "tier-abc123"}'

curl -X PATCH "https://api.devin.ai/v3beta1/enterprise/usage-policies/budgets/budget-abc123/users/user_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cycle_acu_limit": 800, "kind": "temporary"}'
```


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