---
title: "Set individual user groups' AI credit limits"
method: PATCH
path: "/api/v1/ai/credit-controls/user-groups"
tags: ["AI"]
---

# Set individual user groups' AI credit limits

`PATCH /api/v1/ai/credit-controls/user-groups`

## Request

- Base URL: `https://omniapp.co` (the document declares no server; this is the origin it was published from)
- URL: `https://omniapp.co/api/v1/ai/credit-controls/user-groups`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/omniapp/apis/omni-api/docs/api/v1/ai/credit-controls/user-groups/patch.ts> (a function with typed inputs; its response is checked against the schema)

Set individual standard user groups' AI credit limits in bulk. Each entry names a user group by its user group ID (`userGroupId`) and either sets an individual limit (`creditLimit`: a non-negative number, or `null` for unlimited) or removes one (`useDefaultLimit: true`) so the user group follows the org's user-group default (`userGroupDefaultCredits`). A group's limit applies to each member individually, not to the group's combined usage; a member of several groups gets the highest group cap, and an individual per-user or per-entity-group limit takes precedence over group caps. The per-user default (`userDefaultCredits`) still applies alongside a group cap; the lower of the two wins. Each userGroupId may appear at most once and must name a standard (non-embed) user group in the organization. All updates are applied in one transaction, so either every entry takes effect or none do — an unknown userGroupId fails the whole request with a 404 naming it. Requires the same add/remove-users permission as the group settings page and the user-group credit-limit feature flag.

## Request body

- AiUserGroupCreditLimitsUpdateBody
  - `userGroups` AiUserGroupCreditLimitEntry[], required: User groups to update, at most 1000 per request. Each entry has a `userGroupId` plus exactly one of `creditLimit` (number or `null`) or `useDefaultLimit: true`.
    - union
      - object
        - `creditLimit` number, nullable, required: The user group's individual AI credit limit for the billing period, or `null` for unlimited. Either way this overrides the org's user-group default (`userGroupDefaultCredits`). The limit applies to each member individually, not to the group's combined usage; a member of several groups gets the highest group cap, and an individual per-user or per-entity-group limit takes precedence over group caps. The per-user default (`userDefaultCredits`) still applies alongside a group cap; the lower of the two wins. Mutually exclusive with `useDefaultLimit`.
        - `useDefaultLimit` true: Removes the user group's individual limit so it follows the org's user-group default (`userGroupDefaultCredits`). Mutually exclusive with `creditLimit`.
        - `userGroupId` string, required: The user group ID.
      - object
        - `creditLimit` number, nullable: The user group's individual AI credit limit for the billing period, or `null` for unlimited. Either way this overrides the org's user-group default (`userGroupDefaultCredits`). The limit applies to each member individually, not to the group's combined usage; a member of several groups gets the highest group cap, and an individual per-user or per-entity-group limit takes precedence over group caps. The per-user default (`userDefaultCredits`) still applies alongside a group cap; the lower of the two wins. Mutually exclusive with `useDefaultLimit`.
        - `useDefaultLimit` true, required: Removes the user group's individual limit so it follows the org's user-group default (`userGroupDefaultCredits`). Mutually exclusive with `creditLimit`.
        - `userGroupId` string, required: The user group ID.

## Response `200`

All entries applied. Returns each user group's effective limit, in request order.

- AiUserGroupCreditLimitsResponse
  - `userGroups` object[], required
    - `creditLimit` number, nullable, required: The user group's effective per-member AI credit limit, or `null` for unlimited.
    - `name` string, required: The user group's name.
    - `userGroupId` string, required: The user group ID.
    - `usesDefaultLimit` boolean, required: True when the user group has no individual limit and follows the org's user-group default (`userGroupDefaultCredits`).

## Other responses

- `400`: Invalid request. Common causes: an empty userGroups array, more than 1000 entries, an entry with both creditLimit and useDefaultLimit (or neither), a negative creditLimit, or a duplicated userGroupId.
- `401`: Missing or invalid API key.
- `403`: Insufficient permissions, per-user-group AI credit limits are not enabled, or credit controls editing is disabled for the organization.
- `404`: A userGroupId does not name a standard user group in the organization; the response names the first invalid id. No limits are changed.

## Changes

- **2026-11-06** `a3246dd072f3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omniapp/apis/omni-api/changes/api/v1/ai/credit-controls/user-groups/patch.md)

---

[API](https://skmtc.dev/omniapp/apis/omni-api.md) - [All operations](https://skmtc.dev/omniapp/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omniapp/apis/omni-api/revisions/a5c0fcf14508?raw)