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

# Managing AI credits for embed entity groups

> Set default and per-group credit limits for embed entity groups.

Embed entity groups are automatically created groups that correspond to embed entities, defined with the `entity` parameter in embed URL requests. You can set AI credit limits for these groups to control how much AI usage is allowed for users within each entity. This is useful when embedding Omni for multiple customers or tenants and you want to manage AI consumption on a per-entity basis.

## How embed entity group limits work

Along with [organization-level][org-limits] and [user-level][user-limits] AI credit controls, embed entity group controls allow you to limit AI credit consumption at the entity group level.

You can set group-specific limits and a default that applies to all entity groups, allowing you to control how many credits specific groups can consume. For example, you can set a higher limit for groups with more contracted usage and let other groups use the entity group default.

Credit controls can be managed in the [**AI Hub > General > Credits** tab][ai-controls] or programmatically through the [AI credit controls API](/api/ai-credit-controls).

## Requirements

To manage AI credit limits for embed entity groups, you'll need:

* **Organization Admin** permissions
* The **Embed** feature enabled in your Omni instance

<h2 id="embed-entity-default">
  Setting an embed entity group default
</h2>

An embed entity group default applies to all entity groups. When set, the limit will act as the default for any group that doesn't have a [specific limit](#per-group-limits).

<Tabs sync={false} borderBottom="true">
  <Tab title="Omni UI" icon="window-maximize" id="ui-group-default">
    1. Navigate to **AI Hub > General**.
    2. Click the **Credits** tab.
    3. In the **Embed entity settings** section, enter the number of credits in the default limit field, or leave it empty to allow unlimited credits by default.
    4. Click **Save**.
  </Tab>

  <Tab title="API" icon="cloud" id="api-group-default">
    Use the [Update AI credit limits](/api/ai-credit-controls/update-ai-credit-controls) endpoint and include the `entityGroupDefaultCredits` parameter in the request body:

    ```http theme={null}
    curl --request PATCH \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-controls \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "downgradeCredits": 800,
      "shutoffCredits": 1200,
      "userDefaultCredits": 100,
      "entityGroupDefaultCredits": 100
    }
    '
    ```
  </Tab>
</Tabs>

<h2 id="per-group-limits">
  Setting per-group credit limits
</h2>

Each embed entity group has its own detail page where you can configure a credit limit specific to that group. When set:

* The group-level limit will override the [embed entity group default](#embed-entity-default)
* An entity group user's usage will count against [their individual user limit (if set)][user-limits] and their entity group's limit

To configure a credit limit for an embed entity group:

<Tabs sync={false} borderBottom="true">
  <Tab title="Omni UI" icon="window-maximize" id="ui-per-group">
    1. Navigate to **Settings > Groups**.
    2. Click the **Embed** tab to display the list of embed entity groups.
    3. Click the embed entity group you want to manage.
    4. Click the **Settings** tab.
    5. Next to **AI credit limit**, click the **Edit** button.
    6. In the dialog that displays, configure the group's credit limit:
       * **To set a cap**, enter a whole number (ex: `40`) in the **Credit limit** field
       * **To allow unrestricted usage**, click the **Unlimited** toggle
       * **To reset to the [embed entity group default](#embed-entity-default)**, click **Reset to default**
    7. Click **Save**.
  </Tab>

  <Tab title="API" icon="cloud" id="api-per-group">
    Use the [Set individual entity groups' AI credit limits](/api/ai-credit-controls/set-individual-entity-groups-ai-credit-limits) endpoint:

    ```http wrap theme={null}
    curl --request PATCH \
      --url https://<your-instance>.omniapp.co/api/v1/ai/credit-controls/entity-groups \
      --header 'Authorization: Bearer <API_TOKEN>' \
      --header 'Content-Type: application/json' \
      --data '
    {
      "entityGroups": [
        {
          "entity": "blobsrus",
          "creditLimit": 50
        }
      ]
    }
    '
    ```
  </Tab>
</Tabs>

<h2 id="monitor-usage">
  Monitoring entity group credit usage
</h2>

To get an entity group's usage for the current billing period, use the [Read individual entity groups' AI credit limits](/api/ai-credit-usage/read-individual-entity-groups-ai-credit-usage) endpoint and include the entity in the request body's `entities` parameter:

```http wrap theme={null}
curl --request POST \
  --url https://<your-instance>.omniapp.co/api/v1/ai/credit-usage/entity-groups \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entities": [
    "blobsrus"
  ]
}
'
```

## Next steps

* [Managing AI credit usage][ai-controls] — Learn about AI credits, organization-level and user-level controls, and monitoring tools
* [Managing embed users](/embed/admin/users) — View, manage, and impersonate users in your embedded Omni application

[ai-controls]: /ai/settings/usage

[org-limits]: /ai/settings/usage#organization-level-credit-controls

[user-limits]: /ai/settings/usage#user-level-credit-controls