User-level ACU limits

User-level limits are in beta and require the feature to be enabled for your enterprise. To enable this feature, reach out to your account team.

A user-level limit caps the user’s combined local and cloud ACU usage — cloud Devin sessions plus Devin Desktop, Windsurf JetBrains, and Devin CLI count against the same cap. When a user reaches their limit, they cannot start new work on those surfaces until the limit is raised or usage resets in the next monthly window. You can manage tiers and user-level limits from the web app in Enterprise Settings under Usage policies (see the Usage policies guide), or through the usage-policies endpoints below. User-level limits are managed through tiers. A tier is a named, account-wide default limit shared by its members:

Users get into tiers three ways: an admin explicitly assigns them, an IdP group mapping places them (a group maps to a tier, and its members inherit that tier unless explicitly assigned elsewhere), or they fall back to the default tier. Every account can designate one tier as the default tier; every account member not otherwise assigned belongs to it. There is no separate “default user limit” — configure the default tier instead.
Individual users can have an override — either permanent (never expires) or temporary (expires at the end of the current monthly billing window). Overrides are user-scoped: setting one never changes the user’s tier assignment.
A user’s effective limit resolves in this order: permanent override, else a live temporary override, else their explicitly assigned tier’s cycle_acu_limit, else their highest-ranked IdP-group-mapped tier’s limit, else the default tier’s limit. A null limit means uncapped.
Users can ask for a higher limit; admins review these limit-increase requests, and each tier’s policy controls whether requests are auto-approved or held for manual review.

User-level limits are independent of organization-level limits — a request is blocked if either has been reached. See ACU limits for authentication, permissions, and PATCH semantics shared by all endpoints on this page.

The pre-tiers per-user and default user limit endpoints are deprecated; see Legacy user ACU limit endpoints.

Tier endpoints

List tiers

GET /v3beta1/enterprise/usage-policies/tiers

Returns a paginated list of tiers in precedence order: highest priority first, newest tier first within a priority. Each tier looks like:

{
  "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: whether this is the account’s default tier.
cycle_acu_limit: the default per-cycle ACU limit for each member; null means uncapped.
policy: how limit-increase requests against the tier are handled — unconditional and conditional approve up to max_limit, manual requires admin review. The conditional policy (efficiency-based auto-approval) requires separate enablement; reach out to your account team.
max_limit: the maximum limit to which increase requests are approved; null approves without a ceiling. Always null when cycle_acu_limit is null.
priority: ranks the tier among a user’s IdP-group-mapped tiers — the highest value wins, ties broken by newest tier. The ranking is precedence only: a higher-priority tier may have a lower cycle_acu_limit. An explicit user assignment overrides the ranking, and the default tier never ranks.
member_count: the number of users currently in the tier — explicitly assigned users plus users placed by an IdP group mapping. For the default tier this counts every account member not in another tier.

Configure the default tier and tier priority from the web app under Usage policies.

Create a tier

POST /v3beta1/enterprise/usage-policies/tiers

Request body

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

The account’s first tier automatically becomes the default tier. Returns HTTP 201 with the created tier.

Get a tier

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

Update a tier

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

Partial update; omitted fields are unchanged. To change the default tier or tier priority, use the web app under Usage policies.

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

Delete a tier

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

Returns HTTP 204 on success. The default tier cannot be deleted (promote another tier first). A tier that still has users must have them moved first, and any IdP group mappings to the tier must be removed first.

Tier user endpoints

List a tier’s users

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

Returns a paginated list of the tier’s users with their resolved limits — explicitly assigned users plus users placed by an IdP group mapping. For the default tier, this is every account member not in another tier:

{
  "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: the user’s permanent override, if any.
temporary_cycle_acu_limit: the user’s temporary override, present only while it is live in the current monthly billing window.
effective_cycle_acu_limit: the limit currently enforced for the user; null means uncapped.
limit_source: where the effective limit comes from — override (permanent), temporary_override, or tier.
membership: why the user is in the tier — explicit (directly assigned), idp_group (via their winning IdP group mapping), or default (fallback to the default tier).

Assign a user to a tier

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

Idempotent. Returns HTTP 204 on success. Moving a user from another tier clears any per-user override, so they start out inheriting the destination tier’s limit.

Remove a user from a tier

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

Removes the user’s explicit tier assignment (and any override), returning them to the default tier. Returns HTTP 204 on success.

User override endpoint

Set or clear a user’s override

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

User-scoped: the target only needs to be an account member — no tier is involved, and the user’s tier assignment is never changed. A user with only an override (no explicit tier assignment) remains in the default tier. Request body — set a temporary override

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

kind is required when setting a value: permanent never expires; temporary expires at the end of the current monthly billing window. Request body — clear all overrides

{
  "cycle_acu_limit": null
}

The endpoint returns HTTP 204 on success.

IdP group endpoints

Map an IdP group to a tier so its members inherit that tier automatically. Mappings are resolved live from group membership and never change a user’s explicit tier assignment — an explicit assignment always wins. A user in several mapped groups resolves to the highest-ranked mapped tier (highest tier priority, ties broken by newest tier).

List IdP group mappings

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

Returns a paginated list of the account’s group-to-tier mappings, oldest first. Filter with ?tier_id= to list only groups mapped to one tier:

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

Get an IdP group’s mapping

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

Returns HTTP 404 if the group has no mapping.

Map an IdP group to a tier

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

Request body

{
  "tier_id": "tier-abc123"
}

Idempotent upsert. A group maps to at most one tier, so mapping an already-mapped group moves it to the given tier.

Unmap an IdP group

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

Returns HTTP 204 on success. The mapped tier stops applying to the group’s members; users with no explicit assignment and no other mapped tier fall back to the default tier.

Limit-increase request endpoints

Users can request a higher per-cycle limit. The requester’s tier policy decides what happens: unconditional and conditional auto-approve up to the tier’s max_limit, while manual holds the request for admin review through these endpoints (or in Usage policies in the web app).

Unlike the other endpoints on this page, reading limit-increase requests requires the ManageBilling permission — requests carry member identity and free-text messages, which are admin workflow data.

List limit-increase requests

GET /v3beta1/enterprise/usage-policies/requests

Returns a paginated list, filterable with ?status= (pending, approved, denied) and ?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: the requester’s tier (explicit assignment, IdP group mapping, or the default tier); null when the account has no tiers.
current_cycle_acu_limit: the limit currently enforced for the requester; null means uncapped.
reviewer: the admin who reviewed the request; null while pending.

Get a limit-increase request

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

Approve a limit-increase request

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

Grants the requested limit as a temporary override that expires at the end of the current monthly billing window. Optionally grant a different limit:

{
  "cycle_acu_limit": 700
}

Returns the updated request. Returns HTTP 409 if the request was already reviewed or the requester is no longer an account member.

Deny a limit-increase request

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

Returns the updated request, or HTTP 409 if it was already reviewed.

Example workflows

Set up tiers with a default limit

Create a default tier so every user gets a 500 ACU monthly cap:

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

Create a higher-limit tier and assign a user to it:

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

Give a user a temporary bump for the rest of the month:

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

Map an IdP group to the higher-limit tier and review a pending limit request:

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

Frequently asked questions

Which products do user-level limits apply to?

Local and cloud usage: cloud Devin sessions plus local usage from the CLI and IDEs (Devin Desktop, Windsurf JetBrains, and Devin CLI) count against a single cap.

How is a user's effective limit determined?

A permanent override wins first, then a live temporary override, then the user’s explicitly assigned tier’s limit, then their highest-ranked IdP-group-mapped tier’s limit, then the default tier’s limit. A null limit at every level means the user is uncapped.

Do user overrides add to the tier limit?

No. An override replaces the tier limit for that user. If the tier limit is 500 ACUs and a user has an override of 200 ACUs, that user’s effective limit is 200 ACUs.

What is the difference between a permanent and a temporary override?

A permanent override never expires. A temporary override expires at the end of the current monthly billing window, after which the user falls back to their tier’s limit. Approving a limit-increase request grants a temporary override.

Is there still a default user limit?

Not as a standalone setting. Configure the default tier’s limit instead — it applies to every account member not assigned to another tier. The legacy default user limit endpoints now read and write the default tier’s limit.

What happens when someone reaches their limit?

New work is blocked on local and cloud surfaces alike. The user can contact an enterprise administrator to adjust the limit or wait until the next monthly window begins.

Get Started

Essential Guidelines

Onboarding Devin

Working with Devin

Product Guides

Integrations

Admin

Release Notes

User-level ACU limits

Tier endpoints

List tiers

Create a tier

Get a tier

Update a tier

Delete a tier

Tier user endpoints

List a tier’s users

Assign a user to a tier

Remove a user from a tier

User override endpoint

Set or clear a user’s override

IdP group endpoints

List IdP group mappings

Get an IdP group’s mapping

Map an IdP group to a tier

Unmap an IdP group

Limit-increase request endpoints

List limit-increase requests

Get a limit-increase request

Approve a limit-increase request

Deny a limit-increase request

Example workflows

Set up tiers with a default limit

Frequently asked questions

​Tier endpoints

​List tiers

​Create a tier

​Get a tier

​Update a tier

​Delete a tier

​Tier user endpoints

​List a tier’s users

​Assign a user to a tier

​Remove a user from a tier

​User override endpoint

​Set or clear a user’s override

​IdP group endpoints

​List IdP group mappings

​Get an IdP group’s mapping

​Map an IdP group to a tier

​Unmap an IdP group

​Limit-increase request endpoints

​List limit-increase requests

​Get a limit-increase request

​Approve a limit-increase request

​Deny a limit-increase request

​Example workflows

​Set up tiers with a default limit

​Frequently asked questions

Tier endpoints

List tiers

Create a tier

Get a tier

Update a tier

Delete a tier

Tier user endpoints

List a tier’s users

Assign a user to a tier

Remove a user from a tier

User override endpoint

Set or clear a user’s override

IdP group endpoints

List IdP group mappings

Get an IdP group’s mapping

Map an IdP group to a tier

Unmap an IdP group

Limit-increase request endpoints

List limit-increase requests

Get a limit-increase request

Approve a limit-increase request

Deny a limit-increase request

Example workflows

Set up tiers with a default limit

Frequently asked questions