OMomniapp
AI

Read individual user groups' AI credit usage

Changed on

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.

post/api/v1/ai/credit-usage/user-groups

Request

Request body

periodstring

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.

userGroupIdsstring[] required

User groups to read usage for, at most 1000 per request. Each entry is a user group ID.

Example request

{
  "period": "2026-09",
  "userGroupIds": [
    "abc123"
  ]
}

Response

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

periodEndinteger required

Start of the month after the billing period read, as a Unix ms timestamp (UTC calendar-month boundary, exclusive).

periodStartinteger required

Start of the billing period read, as a Unix ms timestamp (UTC calendar-month boundary).

Example response

{
  "userGroups": [
    {
      "creditsUsed": 42,
      "name": "Sales",
      "userGroupId": "abc123"
    }
  ]
}

Changes