用户级 ACU 限额

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

用户级限额会限制用户的本地和云端 ACU 用量总和——云端 Devin 会话、Devin Desktop、Windsurf JetBrains 和 Devin CLI 均计入同一限额。用户达到限额后，在限额提高或下一个月度周期重置用量之前，无法在这些界面上开始新的工作。你可以在 web app 的 企业设置 > 用量策略 中管理层级和用户级限额 (请参阅用量策略指南) ，也可以通过下方的用量策略端点进行管理。用户级限额通过层级管理。层级是由其成员共享的具名账户级默认限额：

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

用户级限额独立于组织级限额——任一限额达到上限时，请求都会被阻止。有关此页面所有端点共用的身份验证、权限和 PATCH 语义，请参阅 ACU 限额。

层级推出前的用户级和默认用户限额端点已弃用；请参阅旧版用户 ACU 限额端点。

层级端点

列出层级

GET /v3beta1/enterprise/usage-policies/tiers

按优先级顺序返回分页的层级列表：priority 最高的排在最前，同一优先级内最新创建的层级排在最前。每个层级的格式如下：

{
  "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 组映射加入的用户。对于默认层级，此项统计所有不属于其他层级的账户成员。

在 web app 的 用量策略 中配置默认层级和层级优先级。

创建层级

POST /v3beta1/enterprise/usage-policies/tiers

请求正文

{
  "name": "Engineers",
  "cycle_acu_limit": 500,
  "policy": "manual"
}

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

获取层级

GET /v3beta1/enterprise/usage-policies/tiers/{tier_id}

更新层级

PATCH /v3beta1/enterprise/usage-policies/tiers/{tier_id}

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

{
  "name": "Engineering",
  "cycle_acu_limit": 750
}

删除层级

DELETE /v3beta1/enterprise/usage-policies/tiers/{tier_id}

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

层级用户端点

列出某个层级的用户

GET /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users

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

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

将用户分配至层级

PUT /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users/{user_id}

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

从层级中移除用户

DELETE /v3beta1/enterprise/usage-policies/tiers/{tier_id}/users/{user_id}

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

用户覆盖端点

设置或清除用户的覆盖配置

PATCH /v3beta1/enterprise/usage-policies/users/{user_id}

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

{
  "cycle_acu_limit": 800,
  "kind": "temporary"
}

设置值时，kind 为必填项：permanent 永不过期；temporary 在当前月度计费周期结束时过期。 请求正文 — 清除所有覆盖

{
  "cycle_acu_limit": null
}

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

IdP 组端点

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

列出 IdP 组映射

GET /v3beta1/enterprise/usage-policies/idp-groups

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

{
  "idp_group_id": "grp_abc123",
  "idp_group_name": "Engineering",
  "tier_id": "tier-abc123"
}

获取 IdP 组映射

GET /v3beta1/enterprise/usage-policies/idp-groups/{idp_group_name}

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

将 IdP 组映射到层级

PUT /v3beta1/enterprise/usage-policies/idp-groups/{idp_group_name}

请求正文

{
  "tier_id": "tier-abc123"
}

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

解除 IdP 组映射

DELETE /v3beta1/enterprise/usage-policies/idp-groups/{idp_group_name}

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

提升限额请求端点

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

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

列出提升限额请求

GET /v3beta1/enterprise/usage-policies/requests

返回分页列表，可通过 ?status= (pending、approved、denied) 和 ?user_id= 进行过滤：

{
  "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。

获取提升限额请求

GET /v3beta1/enterprise/usage-policies/requests/{request_id}

批准提升限额请求

POST /v3beta1/enterprise/usage-policies/requests/{request_id}/approve

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

{
  "cycle_acu_limit": 700
}

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

拒绝提升限额请求

POST /v3beta1/enterprise/usage-policies/requests/{request_id}/deny

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

工作流程示例

设置带默认限额的层级

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

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

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

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>"

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

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 组映射到更高限额的层级，并审核待处理的限额请求：

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>"

常见问题

用户级限额适用于哪些产品？

本地和云端用量均计入同一限额：包括云端 Devin 会话，以及通过 CLI 和 IDE (Devin Desktop、Windsurf JetBrains 和 Devin CLI) 产生的本地用量。

如何确定用户的有效限额？

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

用户覆盖会叠加到层级限额上吗？

不会。覆盖会替换该用户的层级限额。如果层级限额为 500 ACU，而某个用户的覆盖为 200 ACU，则该用户的有效限额为 200 ACU。

永久覆盖和临时覆盖有什么区别？

永久覆盖永不过期。临时覆盖会在当前月度计费周期结束时失效，之后用户将恢复为其层级限额。批准提升限额请求会授予临时覆盖。

是否仍有默认用户限额？

不再作为独立设置提供。请改为配置默认层级限额——该限额适用于未分配到其他层级的所有账户成员。旧版默认用户限额端点现在会读取和写入默认层级限额。

当用户达到限额时会发生什么？

本地和云端界面都将无法启动新工作。用户可以联系 Enterprise Admin 调整限额，或等待下一个月度周期开始。

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Release Notes

用户级 ACU 限额

层级端点

列出层级

创建层级

获取层级

更新层级

删除层级

层级用户端点

列出某个层级的用户

将用户分配至层级

从层级中移除用户

用户覆盖端点

设置或清除用户的覆盖配置

IdP 组端点

列出 IdP 组映射

获取 IdP 组映射

将 IdP 组映射到层级

解除 IdP 组映射

提升限额请求端点

列出提升限额请求

获取提升限额请求

批准提升限额请求

拒绝提升限额请求

工作流程示例

设置带默认限额的层级

常见问题

​层级端点

​列出层级

​创建层级

​获取层级

​更新层级

​删除层级

​层级用户端点

​列出某个层级的用户

​将用户分配至层级

​从层级中移除用户

​用户覆盖端点

​设置或清除用户的覆盖配置

​IdP 组端点

​列出 IdP 组映射

​获取 IdP 组映射

​将 IdP 组映射到层级

​解除 IdP 组映射

​提升限额请求端点

​列出提升限额请求

​获取提升限额请求

​批准提升限额请求

​拒绝提升限额请求

​工作流程示例

​设置带默认限额的层级

​常见问题

层级端点

列出层级

创建层级

获取层级

更新层级

删除层级

层级用户端点

列出某个层级的用户

将用户分配至层级

从层级中移除用户

用户覆盖端点

设置或清除用户的覆盖配置

IdP 组端点

列出 IdP 组映射

获取 IdP 组映射

将 IdP 组映射到层级

解除 IdP 组映射

提升限额请求端点

列出提升限额请求

获取提升限额请求

批准提升限额请求

拒绝提升限额请求

工作流程示例

设置带默认限额的层级

常见问题