> ## 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/api-reference/v3/acu-limits/set-org-devin-acu-limit) でも設定できます。後述の [更新エンドポイント](#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:** フルレビューは実行されなくなります。自動レビューと Devin Review のレビューページから開始したレビューは、検出結果を含まない diff のみの分析にフォールバックします。再実行、API 経由で開始したレビュー、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 人のユーザーが月次期間内に使用できる量の上限です。組織がリンクされた予算はそれぞれ独自のユーザーごとの上限を持ち、その上限は当該予算内でのみ適用されます。

> [!NOTE]
>
> お客様の企業でアカウント全体のユーザーごとの上限をまだ利用している場合、予算への移行方法については [アカウント全体のユーザーごとの上限からの移行](#migrating-from-account-wide-user-limits) を参照してください。

* **階層。** 各予算には独自の階層と、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] 従来のユーザー上限エンドポイントはどうなりますか？
>
> お客様の企業が予算単位のユーザーごとの上限に切り替えた後も、従来のエンドポイントは引き続き応答しますが、その意味が変わります。
>
> * ユーザーを指定し、予算を指定しないエンドポイント (`/v3beta1/enterprise/usage-policies/users/{user_id}`、`/v3beta1/enterprise/users/{user_id}/consumption/acu-limits`) は、1 つの予算、つまりそのユーザーの請求先組織の予算に対してのみ、そのユーザーの上限を設定します。他の予算におけるそのユーザーの上限は変更されません。その組織に予算がない場合、呼び出しは `409` を返します。
> * アカウント全体の階層、IdP グループ、およびデフォルトのユーザー使用量上限のエンドポイント (`/v3beta1/enterprise/usage-policies/tiers`、`/idp-groups`、`/v3beta1/enterprise/users/consumption/acu-limits`) は、引き続きアカウント全体の階層を編集しますが、これらの階層はすでに強制適用されていません。
>
> すべての予算を管理するには、以下の [budget-scoped エンドポイント](#tier-endpoints) を利用してください。

> [accordion] 予算にクラウドとローカルで別々の上限を設定できますか？
>
> いいえ。予算の上限は、クラウドとローカルの使用量を合算した 1 つだけです。組織にクラウドとローカルで別々の上限が設定されている場合は、予算の作成前にアカウント担当チームがそれらを統合します。

> [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"}'
```

## アカウント全体のユーザーごとの上限からの移行

ユーザーごとの上限の設定先は、アカウント階層から予算へ移行します。予算をマージ (オプション 2) しない限り、組織の上限は変わりません。予算でユーザーごとの上限を設定すると、チームごとに個別の上限を設けられるほか、グループとユーザーの上限を一か所で管理できます。

お客様の企業で切り替えが完了するまでは、アカウント全体の階層と上書き設定が引き続き適用されます。

移行するには、予算を編集できる管理者権限が必要です。**エンタープライズ設定** > **使用量ポリシー** を開くと、上部に「User limits are migrating to per-budget user limits.」というバナーが表示されます。バナーをクリックすると、予算の一覧が表示されます。

![Enforce per-budget user limits スイッチと予算の表を含む移行バナー](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-helper.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=c80b438f91a610f79019fb32e1f1a156)

展開して予算を表示した移行バナー

以下の 3 つのオプションからいずれかを選択し、[適用を有効にします](#turn-on-enforcement)。

### オプション 1: ユーザーごとの上限を各予算にコピーする

テーブルヘッダーのチェックボックスですべての予算を選択し、**Copy user limits** をクリックします。すべての予算に現在の階層が適用されます。**What to copy** では、IdPグループマッピング、割り当て、上書き設定がデフォルトで選択されています。これらもコピーする場合は、選択したままにしてください。

![階層、IdPグループマッピング、割り当て、上書き設定が選択された Copy user limits ダイアログ](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-copy-dialog.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=65c9dbc1c03e2cb73d7596cf2a92da57)

選択したすべての予算にユーザーごとの上限をコピー

コピーが完了すると、**Usage tiers** 列に各予算の階層数が表示されます。

![コピー後の予算テーブル。すべての予算に 3 つの使用量階層が設定されている](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-copied.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=f08b8946e5a2c28ab420077cfc8c1904)

コピーされたティアが各予算に設定された状態

複数の予算にまたがって作業するユーザーには、予算ごとに個別の上限が設定されます。そのため、全予算の合計が、移行前のアカウント全体の上限を上回る場合があります。

### オプション 2: ユーザー上限を 1 人につき 1 つにし、組織の上限は適用しない

1. Account 予算を選択し、**Copy user limits** をクリックします。Account 予算がリストにない場合は、先にステップ 2 と 3 を実行してください。組織が含まれると、リストに表示されるようになります。

2. その他の予算をそれぞれ選択し、**Merge into** をクリックして、Account 予算の名前を選択します。

   ![Account 予算以外のすべての予算が選択され、Merge into Account budget ボタンが表示された予算テーブル](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-merge-selected.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=c9fba7bc0436b8b6c3f25d8bce89f827)

   Account 予算にマージするため、その他の予算を選択した状態

3. マージを確定します。

   ![6 つの予算を Account 予算にマージするかを確認するダイアログ](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-merge-dialog.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=a541780cc8b73fdbb11d8d2f62d522b0)

   マージの確定

これらの組織は Account 予算の配下に移動し、各組織の予算はアーカイブされ、組織ごとの上限は適用されなくなります。リストには Account 予算のみが残ります。

![3 つの使用量ティアを持つ Account 予算のみが表示された予算テーブル](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-merged.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=841703de8a194d10ba83032dd4f4b429)

マージ後、すべての組織が Account 予算に含まれた状態

### オプション 3: その他の構成

組織を予算の下にまとめ、予算ごとに異なるユーザーごとの上限を設定します。設定例については、[委任管理者を置く部門](#departments-with-delegated-admins)または[ユーザーごとの上限を高く設定したプロジェクト用予算](#a-project-bucket-with-higher-user-limits)を参照してください。アカウント担当チームと一緒に設定を進めることもできます。

### 適用を有効にする

**Enforce per-budget user limits** をオンにします。確定する前に、現在の請求サイクルでの使用量に基づき、ブロックされることになる人数が Devin に表示されます。

![ブロックされるユーザー数が表示された Enforce per-budget user limits ダイアログ](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-enforce-confirm.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=c093a3a4568a9095cd570d0a8fc2f0ff)

ブロックされる人数を確認して適用を確定する

確定すると、バナーに「Per-budget user limits are in force.」と表示されます。

![スイッチがオンになり、Per-budget user limits are in force と表示されたバナー](https://mintcdn.com/cognitionai/ABQW9Vm6-2kyvMmW/images/admin/budgets/migration-enforced.png?fit=max\&auto=format\&n=ABQW9Vm6-2kyvMmW\&q=85\&s=d035f214116e812d1ce52a2410bff983)

予算単位のユーザーごとの上限が適用された状態

**Enforce per-budget user limits** がオンの間は、アカウント全体の階層と上書き設定は適用されません。各ユーザーには、作業中の予算で設定されたユーザーごとの上限のみが適用されます。階層が設定されていない予算では、その予算内で個別の上書き設定を持つユーザーを除き、ユーザーごとの上限はかかりません。そのため、適用を有効にする前に、ユーザーごとの上限をすべての予算にコピーしておいてください。適用を無効に戻すには、バナーをクリックしてスイッチをオフにし、**Revert to account-wide user limits** を確定します。これで、以前と同じようにアカウント全体の上限が適用されます。

### API で上限を設定している場合

[予算 API](#manage-budgets-with-the-v3-api) を利用してください。この API では、`/v3beta1/enterprise/usage-policies/budgets` 配下で各予算の上限、階層、上書き設定を設定します。[組織の上限 API](https://docs.devin.ai/ja/api-reference/v3/acu-limits/set-org-devin-acu-limit) (`/v3/enterprise/consumption/acu-limits/devin` 配下) は引き続きサポートされます。従来のユーザー上限エンドポイントは、切り替え後に意味が変わります。詳しくは [従来のユーザー上限エンドポイントはどうなりますか？](#frequently-asked-questions) を参照してください。


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