> ## 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 限额

> 通过层级、IdP 组映射和用户级覆盖设置限制每位用户每月的 ACU 用量

<Note>
  用户级限额目前处于 Beta 阶段，需要为你的企业启用此功能。要启用此功能，请联系你的账户团队。
</Note>

用户级限额会限制用户的本地和云端 ACU 用量总和——云端 Devin 会话、Devin Desktop、Windsurf JetBrains 和 Devin CLI 均计入同一限额。用户达到限额后，在限额提高或下一个月度周期重置用量之前，无法在这些界面上开始新的工作。

你可以在 web app 的 **企业设置** > **用量策略** 中管理层级和用户级限额 (请参阅[用量策略指南](/zh/enterprise/features/usage-policies)) ，也可以通过下方的[用量策略端点](#tier-endpoints)进行管理。

用户级限额通过**层级**管理。层级是由其成员共享的具名账户级默认限额：

* 用户可通过三种方式归入层级：由 Admin **显式分配**、通过[**IdP 组映射**](#idp-group-endpoints)归入 (一个组映射到一个层级，其成员会继承该层级，除非被显式分配到其他层级) ，或归入**默认层级**。每个账户可以指定一个层级作为默认层级；所有未被另行分配的账户成员均属于该层级。不存在单独的“默认用户限额”——请改为配置默认层级。
* 单个用户可以有**覆盖**——可以是**永久**的 (永不过期) ，也可以是**临时**的 (在当前月度计费周期结束时过期) 。覆盖以用户为作用域：设置覆盖绝不会更改用户的层级分配。
* 用户的**有效限额**按以下顺序确定：永久覆盖；否则为仍有效的临时覆盖；否则为其显式分配层级的 `cycle_acu_limit`；否则为其 IdP 组映射层级中排名最高的层级限额；否则为默认层级的限额。`null` 限额表示不设上限。
* 用户可以申请提高限额；Admin 会审核这些[**提升限额请求**](#limit-increase-request-endpoints)，每个层级的 `policy` 控制请求是自动批准，还是保留供手动审核。

用户级限额独立于[组织级限额](/zh/admin/billing/org-acu-limits)——任一限额达到上限时，请求都会被阻止。有关此页面所有端点共用的身份验证、权限和 `PATCH` 语义，请参阅 [ACU 限额](/zh/admin/billing/acu-limits)。

<Warning>
  层级推出前的用户级和默认用户限额端点已弃用；请参阅[旧版用户 ACU 限额端点](/zh/admin/billing/legacy-user-acu-limits)。
</Warning>

<div id="tier-endpoints">
  ## 层级端点
</div>

<div id="list-tiers">
  ### 列出层级
</div>

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

按优先级顺序返回分页的层级列表：`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` 则需要 Admin 审核。`conditional` 策略 (基于效率的自动批准) 需单独启用；请联系你的账户团队。
* `max_limit`：提升限额请求可获批的最高限额；`null` 表示批准时不设上限。当 `cycle_acu_limit` 为 `null` 时，该值始终为 `null`。
* `priority`：对用户通过 IdP 组映射获得的层级进行排序——值最高者优先生效；若值相同，则以创建时间最新的层级为准。此排序仅用于确定优先级：优先级较高的层级的 `cycle_acu_limit` 可能较低。显式分配给用户的层级会覆盖此排序，默认层级不参与排序。
* `member_count`：当前属于该层级的用户数量——包括显式分配的用户，以及通过 IdP 组映射加入的用户。对于默认层级，此项统计所有不属于其他层级的账户成员。

<Note>
  在 web app 的 **用量策略** 中配置默认层级和层级优先级。
</Note>

<div id="create-a-tier">
  ### 创建层级
</div>

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

**请求正文**

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

账户的第一个层级会自动设为默认层级。返回 HTTP `201` 和已创建的层级。

<div id="get-a-tier">
  ### 获取层级
</div>

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

<div id="update-a-tier">
  ### 更新层级
</div>

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

部分更新；未提供的字段保持不变。要更改默认层级或层级优先级，请在 web app 的 **用量策略** 中操作。

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

<div id="delete-a-tier">
  ### 删除层级
</div>

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

成功时返回 HTTP `204`。默认层级无法删除 (请先提升其他层级) 。如果某个层级仍有用户，必须先将用户迁移至其他层级；此外，还必须先移除该层级的所有 IdP 组映射。

<div id="tier-user-endpoints">
  ## 层级用户端点
</div>

<div id="list-a-tiers-users">
  ### 列出某个层级的用户
</div>

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

返回该层级用户及其解析后的限额的分页列表——包括显式分配的用户，以及通过 IdP 组映射加入的用户。对于默认层级，这包括未分配到其他层级的所有账户成员：

```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` (回退到默认层级) 。

<div id="assign-a-user-to-a-tier">
  ### 将用户分配至层级
</div>

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

幂等操作。成功时返回 HTTP `204`。将用户从其他层级移入会清除所有用户级覆盖设置，因此该用户将继承目标层级的 limit。

<div id="remove-a-user-from-a-tier">
  ### 从层级中移除用户
</div>

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

移除用户的显式层级分配 (及任何覆盖设置) ，使其恢复为默认层级。成功时返回 HTTP `204`。

<div id="user-override-endpoint">
  ## 用户覆盖端点
</div>

<div id="set-or-clear-a-users-override">
  ### 设置或清除用户的覆盖配置
</div>

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

用户作用域：目标只需是账户成员——不涉及层级，且不会更改用户的层级分配。仅设置覆盖项 (未显式分配层级) 的用户仍处于默认层级。

**请求正文 — 设置临时覆盖**

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

设置值时，`kind` 为必填项：`permanent` 永不过期；`temporary` 在当前月度计费周期结束时过期。

**请求正文 — 清除所有覆盖**

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

操作成功时，该端点返回 HTTP `204`。

<div id="idp-group-endpoints">
  ## IdP 组端点
</div>

将 IdP 组映射到层级后，其成员会自动继承该层级。映射会根据组成员关系实时解析，且绝不会更改用户显式分配的层级——显式分配始终优先。属于多个已映射组的用户将解析为排名最高的已映射层级 (`priority` 最高的层级；如相同，则以最新的层级为准) 。

<div id="list-idp-group-mappings">
  ### 列出 IdP 组映射
</div>

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

返回账户的组到层级映射分页列表，按创建时间从早到晚排序。使用 `?tier_id=` 过滤器可仅列出映射到特定层级的组：

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

<div id="get-an-idp-groups-mapping">
  ### 获取 IdP 组映射
</div>

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

如果该组未配置映射，则返回 HTTP `404`。

<div id="map-an-idp-group-to-a-tier">
  ### 将 IdP 组映射到层级
</div>

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

**请求正文**

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

幂等式更新插入。一个组最多只能映射到一个层级；因此，将已映射的组映射到新的层级会将其移至该层级。

<div id="unmap-an-idp-group">
  ### 解除 IdP 组映射
</div>

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

成功时返回 HTTP `204`。该映射层级将不再适用于该组成员；未获显式分配且没有其他映射层级的用户将回退到默认层级。

<div id="limit-increase-request-endpoints">
  ## 提升限额请求端点
</div>

用户可以申请提高每周期限额。请求者所在层级的 `policy` 决定处理方式：`unconditional` 和 `conditional` 会自动批准不超过该层级 `max_limit` 的提升限额请求；`manual` 则会保留提升限额请求，由 Admin 通过这些端点 (或 web app 中的 **用量策略**) 进行审核。

<Note>
  与本页的其他端点不同，读取提升限额请求需要 **ManageBilling** 权限，因为提升限额请求中包含成员身份和自由文本消息，这些均属于 Admin 工作流程数据。
</Note>

<div id="list-limit-increase-requests">
  ### 列出提升限额请求
</div>

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

返回分页列表，可通过 `?status=` (`pending`、`approved`、`denied`) 和 `?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`：请求者所属的层级 (显式分配、IdP 组映射或默认层级) ；如果账户未配置任何层级，则为 `null`。
* `current_cycle_acu_limit`：当前对请求者执行的限额；`null` 表示未设上限。
* `reviewer`：审查该请求的 Admin；请求待处理期间为 `null`。

<div id="get-a-limit-increase-request">
  ### 获取提升限额请求
</div>

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

<div id="approve-a-limit-increase-request">
  ### 批准提升限额请求
</div>

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

将请求的限额作为**临时覆盖**授予，并在当前月度计费周期结束时到期。也可以选择授予其他限额：

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

返回更新后的请求。如果该请求已被审查，或请求者不再是账户成员，则返回 HTTP `409`。

<div id="deny-a-limit-increase-request">
  ### 拒绝提升限额请求
</div>

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

返回更新后的请求；如果该请求已被审查，则返回 HTTP `409`。

<div id="example-workflows">
  ## 工作流程示例
</div>

<div id="set-up-tiers-with-a-default-limit">
  ### 设置带默认限额的层级
</div>

创建一个默认层级，为每位用户设置每月 500 ACU 的上限：

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

创建更高额度的层级，并将用户分配至该层级：

```bash theme={null}
curl -X POST "https://api.devin.ai/v3beta1/enterprise/usage-policies/tiers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Power users", "cycle_acu_limit": 2000, "policy": "manual"}'

curl -X PUT "https://api.devin.ai/v3beta1/enterprise/usage-policies/tiers/tier-abc123/users/user_abc123" \
  -H "Authorization: Bearer <token>"
```

在本月剩余时间内，临时上调某位用户的额度：

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

将 IdP 组映射到更高限额的层级，并审核待处理的限额请求：

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

curl -X POST "https://api.devin.ai/v3beta1/enterprise/usage-policies/requests/42/approve" \
  -H "Authorization: Bearer <token>"
```

<div id="frequently-asked-questions">
  ## 常见问题
</div>

<AccordionGroup>
  <Accordion title="用户级限额适用于哪些产品？">
    本地和云端用量均计入同一限额：包括云端 Devin 会话，以及通过 CLI 和 IDE (Devin Desktop、Windsurf JetBrains 和 Devin CLI) 产生的本地用量。
  </Accordion>

  <Accordion title="如何确定用户的有效限额？">
    优先级依次为：永久覆盖、当前生效的临时覆盖、显式分配给用户的层级限额、用户通过 IdP 组映射到的层级中排名最高的限额，以及默认层级限额。如果所有层级的限额均为 `null`，则该用户不受限额约束。
  </Accordion>

  <Accordion title="用户覆盖会叠加到层级限额上吗？">
    不会。覆盖会替换该用户的层级限额。如果层级限额为 500 ACU，而某个用户的覆盖为 200 ACU，则该用户的有效限额为 200 ACU。
  </Accordion>

  <Accordion title="永久覆盖和临时覆盖有什么区别？">
    永久覆盖永不过期。临时覆盖会在当前月度计费周期结束时失效，之后用户将恢复为其层级限额。批准提升限额请求会授予临时覆盖。
  </Accordion>

  <Accordion title="是否仍有默认用户限额？">
    不再作为独立设置提供。请改为配置默认层级限额——该限额适用于未分配到其他层级的所有账户成员。[旧版默认用户限额端点](/zh/admin/billing/legacy-user-acu-limits#default-user-limit-endpoints)现在会读取和写入默认层级限额。
  </Accordion>

  <Accordion title="当用户达到限额时会发生什么？">
    本地和云端界面都将无法启动新工作。用户可以联系 Enterprise Admin 调整限额，或等待下一个月度周期开始。
  </Accordion>
</AccordionGroup>