---
title: "Read individual user groups' AI credit usage"
method: POST
path: "/api/v1/ai/credit-usage/user-groups"
tags: ["AI"]
---

# Read individual user groups' AI credit usage

`POST /api/v1/ai/credit-usage/user-groups`

## Request

- Base URL: `https://omniapp.co` (the document declares no server; this is the origin it was published from)
- URL: `https://omniapp.co/api/v1/ai/credit-usage/user-groups`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/omniapp/apis/omni-api/docs/api/v1/ai/credit-usage/user-groups/post.ts> (a function with typed inputs; its response is checked against the schema)

Read individual standard user groups' AI credit usage for one billing period: the current UTC calendar month by default, or an earlier month named by `period` as `YYYY-MM`. Names the user groups by user group ID (`userGroupId`); each must name a standard (non-embed) user group in the organization at the time of the request, even when reading a past month. Returns each user group's credits used and name, in request order, plus the bounds of the period read. A user group's usage is the sum of its current members' own usage, so a past month reflects today's membership: a member of several groups counts toward each, and totals across groups can exceed the organization's total. The number is informational — a group's limit applies to each member individually, not to the group's combined usage. A user group with no usage in that period reports 0. At most 1000 ids per request; each userGroupId may appear at most once. An unknown userGroupId fails the whole request with a 404 naming it; a `period` after the current month fails with a 400. This is a read, so it works even when credit-controls editing is disabled; it requires the same add/remove-users permission and user-group credit-limit feature flag as the per-user-group limit endpoints.

## Request body

- AiCreditUsageUserGroupsBody
  - `period` string: UTC calendar month to read, as `YYYY-MM`, from `2000-01` to `2099-12`. Omit it to read the current billing period. A month after the current one is rejected; a month before AI credit metering began reports `0` for every id.
  - `userGroupIds` string[], required: User groups to read usage for, at most 1000 per request. Each entry is a user group ID.

## Response `200`

Each requested user group's credit usage for the billing period read, in request order.

- AiCreditUsageUserGroupsResponse
  - `periodEnd` integer, required: Start of the month after the billing period read, as a Unix ms timestamp (UTC calendar-month boundary, exclusive).
  - `periodStart` integer, required: Start of the billing period read, as a Unix ms timestamp (UTC calendar-month boundary).
  - `userGroups` object[], required
    - `creditsUsed` number, required: Credits the id consumed in the billing period read. `0` when it has no usage in that period.
    - `name` string, required: The user group's name.
    - `userGroupId` string, required: The user group ID.

## Other responses

- `400`: Invalid request. Common causes: an empty userGroupIds array, more than 1000 ids, a duplicated userGroupId, or a period that is not a month from 2000-01 to 2099-12 written as YYYY-MM, or is after the current month.
- `401`: Missing or invalid API key.
- `403`: Insufficient permissions, or per-user-group AI credit limits are not enabled for the organization.
- `404`: A userGroupId does not name a standard user group in the organization; the response names the first invalid id.

## Changes

- **2026-11-06** `a3246dd072f3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omniapp/apis/omni-api/changes/api/v1/ai/credit-usage/user-groups/post.md)

---

[API](https://skmtc.dev/omniapp/apis/omni-api.md) - [All operations](https://skmtc.dev/omniapp/apis/omni-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omniapp/apis/omni-api/revisions/a5c0fcf14508?raw)