> ## 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.

# Set individual entity groups' AI credit limits

> <Note>
  **Organization Admin** permissions are required to use this endpoint.
</Note>

Set individual embed entity groups' AI credit limits in bulk. Each entry names an entity group and either sets an individual limit or removes one so the entity group follows the organization default. All entries are applied in a single transaction.


<Tip>
  To set an unlimited override for an entity group, use `creditLimit: null`. This is distinct from having the entity group follow the organization default.
</Tip>


## OpenAPI

````yaml /api/openapi.yaml patch /v1/ai/credit-controls/entity-groups
openapi: 3.1.0
info:
  title: Omni API
  description: >
    The Omni REST API provides programmatic access to your Omni instance for
    managing users, documents, queries, schedules, and more.  
  version: 1.0.0
  contact:
    name: Omni Support
    url: https://docs.omni.co
servers:
  - url: https://{instance}.omniapp.co/api
    description: Production
    variables:
      instance:
        default: blobsrus
        description: Your production Omni instance subdomain
  - url: https://{instance}.playground.exploreomni.dev/api
    description: Playground
    variables:
      instance:
        default: blobsrus
        description: Your playground Omni instance subdomain
security:
  - bearerAuth: []
  - orgApiKey: []
tags:
  - name: Who Am I
    description: Inspect your own user permissions
  - name: AI
    description: AI-powered query generation
  - name: AI Credit Controls
    description: Manage organization-level AI credit usage
  - name: AI Credit Usage
    description: Monitor AI credit usage
  - name: AI Evals
    description: >-
      Manage prompt sets and runs used to score AI quality against curated
      prompt suites.
  - name: AI Model Suggestions
    description: Manage AI-generated suggestions for shared models
  - name: AI Routines
    description: >-
      Manage Routines, which are scheduled, recurring AI-powered tasks that run
      automatically on your data
  - name: Documents v2
    description: >
      A draft-based workflow for creating and editing documents: create a
      document, patch a draft, then publish. Replaces the one-shot `PUT`/`PATCH`
      v1 document write endpoints.
  - name: Documents
    description: Create, retrieve, and manage documents
  - name: API Tokens
    description: >-
      Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
      grants)
  - name: Connections
    description: Manage database connections
  - name: Connection environments
    description: Manage connection environments database connections
  - name: Content
    description: Unified content retrieval (documents and folders)
  - name: Content migration
    description: Export and import dashboards
  - name: Content validator
    description: Validate content against models and perform find/replace operations
  - name: Dashboard downloads
    description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
  - name: Dashboard filters and controls
    description: Read and update dashboard filter and control default values
  - name: dbt
    description: Manage dbt configuration for connections
  - name: Document favorites
    description: Favorite and unfavorite documents
  - name: Document labels
    description: Apply and manage labels on documents
  - name: Document permissions
    description: Manage document-level access
  - name: Labels
    description: |
      Manage labels in the organization
  - name: Folders
    description: Create and organize content folders
  - name: Folder permissions
    description: Manage folder-level access
  - name: Jobs
    description: Check status of asynchronous jobs
  - name: Models
    description: Create and manage data models
  - name: Model branches
    description: Manage model branches and merge changes
  - name: Model git configuration
    description: Manage git configuration for shared models
  - name: Queries
    description: Execute workbook queries
  - name: Schedules
    description: Create and manage scheduled tasks
  - name: Schedule recipients
    description: Manage schedule recipients
  - name: Schema refresh schedules
    description: Manage automated schema refresh schedules for connections
  - name: Topics
    description: Retrieve topic information from models
  - name: Uploads
    description: Manage file uploads
  - name: Users
    description: Manage users
  - name: User attributes
    description: Manage user attribute definitions
  - name: User groups
    description: Manage user groups
  - name: User model roles
    description: Manage model and connection role assignments for users
  - name: User group model roles
    description: Manage model and connection role assignments for user groups
  - name: Uploads
    description: Manage CSV and spreadsheet uploads
paths:
  /v1/ai/credit-controls/entity-groups:
    patch:
      tags:
        - AI Credit Controls
      summary: Set individual entity groups' AI credit limits
      description: >
        <Note>
          **Organization Admin** permissions are required to use this endpoint.
        </Note>


        Set individual embed entity groups' AI credit limits in bulk. Each entry
        names an entity group and either sets an individual limit or removes one
        so the entity group follows the organization default. All entries are
        applied in a single transaction.
      operationId: aiCreditControlsEntityGroupsUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - entityGroups
              additionalProperties: false
              properties:
                entityGroups:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  description: >
                    Entity groups to update. Each entry has an `entity` plus
                    exactly one of `creditLimit` (number or `null`) or
                    `useDefaultLimit: true`.
                  items:
                    type: object
                    required:
                      - entity
                    additionalProperties: false
                    properties:
                      creditLimit:
                        type: number
                        nullable: true
                        minimum: 0
                        description: >-
                          The entity group's individual AI credit limit for the
                          billing period, or `null` for unlimited. This will
                          override the organization default. Mutually exclusive
                          with `useDefaultLimit`.
                        example: 50
                      entity:
                        type: string
                        description: >-
                          The embed entity's identifier (the SSO `entity`
                          value).
                        example: blobsrus
                      useDefaultLimit:
                        type: boolean
                        description: >-
                          Removes the entity group's individual limit so it
                          follows the organization default. Mutually exclusive
                          with `creditLimit`.
            examples:
              Set limits for 2 entity groups:
                summary: Set limits for two entity groups
                value:
                  entityGroups:
                    - entity: blobsrus
                      creditLimit: 50
                    - entity: blobsrus-eu
                      creditLimit: null
              Remove individual limit:
                summary: Remove individual limit
                value:
                  entityGroups:
                    - entity: blobsrus
                      useDefaultLimit: true
      responses:
        '200':
          description: >-
            All entries applied. Returns each entity group's effective limit, in
            request order.
          content:
            application/json:
              schema:
                type: object
                required:
                  - entityGroups
                properties:
                  entityGroups:
                    type: array
                    items:
                      type: object
                      required:
                        - creditLimit
                        - entity
                        - usesDefaultLimit
                      properties:
                        creditLimit:
                          type: number
                          nullable: true
                          minimum: 0
                          description: >-
                            The entity group's effective AI credit limit, or
                            `null` for unlimited.
                          example: 50
                        entity:
                          type: string
                          description: >-
                            The embed entity's identifier (the SSO `entity`
                            value).
                          example: blobsrus
                        usesDefaultLimit:
                          type: boolean
                          description: >
                            If `true`, the entity group has no individual limit
                            and follows the organization default.
        '400':
          description: |
            Invalid request. Common causes:

            - An empty `entityGroups` array
            - More than 1000 entries
            - An entry with both `creditLimit` and `useDefaultLimit`, or neither
            - A negative `creditLimit`
            - A duplicated `entity`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError400'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError401'
        '403':
          description: >-
            Insufficient permissions, per-entity-group AI credit limits are not
            enabled, or credit controls editing is disabled for the
            organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError403'
        '404':
          description: >-
            An entity has no entity group in the organization; the response
            names the first invalid entity. No limits are changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError404'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ApiError400:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 400
      required:
        - detail
        - status
    ApiError401:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
          example: 'Unauthorized: Missing or invalid API key'
        status:
          type: integer
          description: HTTP status code of the error.
          example: 401
      required:
        - detail
        - status
    ApiError403:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 403
      required:
        - detail
        - status
    ApiError404:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
        status:
          type: integer
          description: HTTP status code of the error.
          example: 404
      required:
        - detail
        - status
    Error:
      type: object
      properties:
        error:
          type: string
          description: HTTP response code for the error
          example: <response_code>
        message:
          type: string
          description: Detailed error description
          example: <error_reason>
  responses:
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded (60 requests/minute)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Can be either an [Organization API
        Key](/api/authentication#organization-api-keys) or [Personal Access
        Token (PAT)](/api/authentication#token-types).


        Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
    orgApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Requires an [Organization API
        Key](/api/authentication#organization-api-keys). Personal Access Tokens
        (PATs) are not supported for this endpoint.


        Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`

````