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

# Set individual entity groups' AI credit limits

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

Set individual embed entity groups' AI credit limits in bulk. Each entry names an entity group by its embed `entity` string and either sets an individual limit (`creditLimit`: a non-negative number, or `null` for unlimited) or removes one (`useDefaultLimit: true`) so the entity group follows the org default. Each entity may appear at most once and must have an entity group in the organization. All updates are applied in one transaction, so either every entry takes effect or none do — an unknown entity fails the whole request with a 404 naming it. Requires the same add/remove-users permission as the group settings page and the embed-entity credit-limit feature flag.

## Request body

- AiEntityGroupCreditLimitsUpdateBody
  - `entityGroups` AiEntityGroupCreditLimitEntry[], required — Entity groups to update, at most 1000 per request. Each entry has an `entity` plus exactly one of `creditLimit` (number or `null`) or `useDefaultLimit: true`.
    - `creditLimit` number, nullable — The entity group's individual AI credit limit for the billing period, or `null` for unlimited. Either way this overrides the org default. Mutually exclusive with `useDefaultLimit`.
    - `entity` string, required — The embed entity's identifier (the SSO `entity` value).
    - `useDefaultLimit` true — Removes the entity group's individual limit so it follows the org default. Mutually exclusive with `creditLimit`.

## Response `200`

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

- AiEntityGroupCreditLimitsResponse
  - `entityGroups` object[], required
    - `creditLimit` number, nullable, required — The entity group's effective AI credit limit, or `null` for unlimited.
    - `entity` string, required — The embed entity's identifier (the SSO `entity` value).
    - `usesDefaultLimit` boolean, required — True when the entity group has no individual limit and follows the org default.

## Other responses

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

---

[API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/versions/de7cac8b5983/schema)