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

# User-level ACU limits

> Cap each user's monthly ACU consumption with tiers, IdP group mappings, and per-user overrides

<Note>
  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.
</Note>

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](/enterprise/features/usage-policies)), or through the [usage-policies endpoints](#tier-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**](#idp-group-endpoints) 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**](#limit-increase-request-endpoints), 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](/admin/billing/org-acu-limits) — a request is blocked if either has been reached. See [ACU limits](/admin/billing/acu-limits) for authentication, permissions, and `PATCH` semantics shared by all endpoints on this page.

<Warning>
  The pre-tiers per-user and default user limit endpoints are deprecated; see [Legacy user ACU limit endpoints](/admin/billing/legacy-user-acu-limits).
</Warning>

## Tier endpoints

### List tiers

```http theme={null}
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:

```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`: 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.

<Note>
  Configure the default tier and tier priority from the web app under **Usage policies**.
</Note>

### Create a tier

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

**Request body**

```json theme={null}
{
  "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

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

### Update a tier

```http theme={null}
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**.

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

### Delete a tier

```http theme={null}
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

```http theme={null}
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:

```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`: 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

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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

```http theme={null}
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:

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

### Get an IdP group's mapping

```http theme={null}
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

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

**Request body**

```json theme={null}
{
  "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

```http theme={null}
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).

<Note>
  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.
</Note>

### List limit-increase requests

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

Returns a paginated list, filterable with `?status=` (`pending`, `approved`, `denied`) and `?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`: 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

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

### Approve a limit-increase request

```http theme={null}
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:

```json theme={null}
{
  "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

```http theme={null}
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:

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

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

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

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

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

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

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

## Frequently asked questions

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/admin/billing/legacy-user-acu-limits#default-user-limit-endpoints) now read and write the default tier's limit.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>