> ## 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 users' AI credit limits

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

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




## OpenAPI

````yaml /api/openapi.yaml patch /v1/ai/credit-controls/users
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 Eval
    description: >-
      AI evaluation: 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 AI Routines: schedule recurring AI-powered tasks to 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 an organization. Labels can be applied to documents and
      folders to help organize and categorize content.


      **Label types:**

      - **Basic labels**: Can be created and managed by any user

      - **Verified labels**: Indicate curated or officially sanctioned content.
      Admin-only.

      - **Homepage labels**: Appear on the organization homepage. Admin-only.
  - 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/users:
    patch:
      tags:
        - AI Credit Controls
      summary: Set individual users' AI credit limits
      description: >
        <Note>
          **Organization Admin** permissions are required to use this endpoint.
        </Note>


        Set individual users' AI credit limits in bulk. Each entry names a user
        and either sets an individual limit or removes one so the user follows
        the organization default. All entries are applied in a single
        transaction.
      operationId: aiCreditControlsUsersUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  type: array
                  items:
                    type: object
                    properties:
                      creditLimit:
                        type: number
                        nullable: true
                        minimum: 0
                        description: >-
                          The user'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
                      useDefaultLimit:
                        type: boolean
                        enum:
                          - true
                        description: >-
                          Removes the user's individual limit so they follow the
                          organization default. Mutually exclusive with
                          `creditLimit`.
                      userId:
                        type: string
                        description: The user's ID within this organization.
                        example: f4a2b3c8-0d1e-4f5a-9b6c-7d8e9f0a1b2c
                    required:
                      - userId
                    additionalProperties: false
                  minItems: 1
                  maxItems: 1000
                  description: >-
                    Users to update, at most 1000 per request. Each entry has a
                    `userId` plus exactly one of `creditLimit` (number or
                    `null`) or `useDefaultLimit: true`.
              required:
                - users
              additionalProperties: false
            examples:
              set_limits:
                summary: Set limits for two users
                value:
                  users:
                    - userId: f4a2b3c8-0d1e-4f5a-9b6c-7d8e9f0a1b2c
                      creditLimit: 50
                    - userId: a7b8c9d0-e1f2-3a4b-5c6d-7e8f9a0b1c2d
                      creditLimit: null
              reset_to_default:
                summary: Remove individual limit
                value:
                  users:
                    - userId: f4a2b3c8-0d1e-4f5a-9b6c-7d8e9f0a1b2c
                      useDefaultLimit: true
      responses:
        '200':
          description: >-
            All entries applied. Returns each user's effective limit, in request
            order.
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        creditLimit:
                          type: number
                          nullable: true
                          minimum: 0
                          description: >-
                            The user's effective AI credit limit, or `null` for
                            unlimited.
                          example: 50
                        userId:
                          type: string
                          description: The user's ID within this organization.
                          example: f4a2b3c8-0d1e-4f5a-9b6c-7d8e9f0a1b2c
                        usesDefaultLimit:
                          type: boolean
                          description: >
                            If `true`, the user has no individual limit and
                            follows the organization default.
                      required:
                        - creditLimit
                        - userId
                        - usesDefaultLimit
        '400':
          description: >
            Invalid request. Common causes:


            - An empty users array

            - More than 1000 entries

            - An entry with both `creditLimit` and `useDefaultLimit` (or
            neither)

            - A negative `creditLimit`

            - A duplicated `userId`
          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-user 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: >-
            Specified `userId` is not a member of the organization; the response
            names the first invalid id. 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.
          example: 'Bad Request: prompt: Required'
        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.
          example: 'Forbidden: AI query generation is not enabled for this organization'
        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.
          example: Model 770e8400-e29b-41d4-a716-446655440002 not found
        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`

````