> ## 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.
# Read individual user groups' AI credit usage
>
**Organization Admin** permissions are required to use this endpoint.
List AI credit usage for user groups (up to 1,000 unique user groups per request) for one billing period: the current UTC calendar month by default, or an earlier month named by the `period` field. Unknown, invalid, and duplicate IDs will fail the request.
Returns each user group's credits used, in request order, plus the bounds of the period read. A user group's usage is the sum of its current members' usage for the period. User groups with no members or no usage in that period will report `0`.
> [!NOTE]
>
> This total is for information only. A user group's credit limit applies to each member individually, so Omni doesn't compare the group total to a limit.
>
> Group totals can be more than the organization total, because a member of more than one group counts toward the total of each group. Unlike the [Read individual users' AI credit usage](https://docs.omni.co/api/ai-credit-usage/read-individual-users-ai-credit-usage.md) endpoint, this total includes usage by Omni support accounts.
## OpenAPI
````yaml /api/openapi.yaml post /v1/ai/credit-usage/user-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: Apps
description: Draft and publish app documents.
- name: App downloads
description: Download apps as PNG, PDF, XLSX, or CSV files
- name: Branches
description: List branches and open or close them to Viewers and Restricted Queriers
- name: Documents v2
description: >
A draft-based workflow for creating and editing documents: create a
document, patch a draft, then publish.
- name: Documents
description: Create, retrieve, and manage documents
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: IP Allowlist
description: Manage the organization's IP allowlist
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Color Palettes
description: Manage custom chart color palettes
- 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: Embed
description: Manage embed sessions
- name: Labels
description: |
Manage labels in the organization
- name: Folders
description: Create and organize content folders
- name: Folder favorites
description: Favorite and unfavorite folders
- name: Folder labels
description: Apply and manage labels on 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: Skills
description: >-
Manage skills, the saved slash-command instructions the Omni AI assistant
runs
- 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-usage/user-groups:
post:
tags:
- AI Credit Usage
summary: Read individual user groups' AI credit usage
description: >
**Organization Admin** permissions are required to use this endpoint.
List AI credit usage for user groups (up to 1,000 unique user groups per
request) for one billing period: the current UTC calendar month by
default, or an earlier month named by the `period` field. Unknown,
invalid, and duplicate IDs will fail the request.
Returns each user group's credits used, in request order, plus the
bounds of the period read. A user group's usage is the sum of its
current members' usage for the period. User groups with no members or no
usage in that period will report `0`.
operationId: aiCreditUsageUserGroupsRead
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- userGroupIds
additionalProperties: false
properties:
period:
type: string
pattern: ^20\d{2}-(0[1-9]|1[0-2])$
description: >
UTC calendar month to read, as `YYYY-MM`. Omit it to read
the current billing period. A month after the current one is
rejected.
example: 2026-09
userGroupIds:
type: array
items:
type: string
example: mEhXj6ZI
minItems: 1
maxItems: 1000
description: >
User groups to read usage for, at most 1000 per request.
Each entry is a user group's ID. Use the [List user
groups](/api/user-groups/list-user-groups) endpoint to
retrieve user group IDs. Each ID must be included only once.
responses:
'200':
description: >-
Each requested user group's credit usage for the billing period
read, in request order.
content:
application/json:
schema:
type: object
required:
- periodEnd
- periodStart
- userGroups
properties:
periodEnd:
type: integer
minimum: 0
description: >-
Start of the month after the billing period read, as a
Unix ms timestamp (UTC calendar-month boundary,
exclusive).
example: 1790812800000
periodStart:
type: integer
minimum: 0
description: >-
Start of the billing period read, as a Unix ms timestamp
(UTC calendar-month boundary).
example: 1788220800000
userGroups:
type: array
items:
type: object
required:
- creditsUsed
- name
- userGroupId
properties:
creditsUsed:
type: number
minimum: 0
description: >-
Sum of the credits that the user group's current
members consumed in the billing period read. `0`
when the group has no members or no usage in that
period.
example: 42
name:
type: string
description: The user group's name.
example: Blob Sales
userGroupId:
type: string
description: The user group's ID.
example: mEhXj6ZI
'400':
description: >
Invalid request. Common causes: an empty `userGroupIds` array, more
than 1000 IDs, a duplicated ID, or a `period` that isn't written as
`YYYY-MM` or that's after the current month.
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: >-
A `userGroupId` is unknown, belongs to another organization, or is
an embed entity group's ID; the response names the first invalid ID
in request order.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
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
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`
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.