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

# Read individual entity groups' AI credit usage

`POST /v1/ai/credit-usage/entity-groups`

## Request

- Base URL: `https://blobsrus.omniapp.co/api`
- URL: `https://blobsrus.omniapp.co/api/v1/ai/credit-usage/entity-groups`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

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

List individual embed entity groups' (up to 1,000 unique entities per request) AI credit usage for the current billing period. Each included `entity` must have an entity group in the organization. Unknown, invalid, and duplicate `entity` values will fail the request.

Returns each entity group's credits used, in request order, plus the billing-period bounds. Entity groups with no current usage will report `0`.

## Request body

- object
  - `entities` string[], required: Entity groups to read usage for, at most 1000 per request. Each entry is an embed `entity` (the SSO `entity` value) corresponding to an entity group in the organization. Each entity must be included only once, as duplicated entries will fail the request.

## Response `200`

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

- object
  - `periodEnd` integer, required: End of the current billing period as a Unix ms timestamp (UTC calendar-month boundary).
  - `periodStart` integer, required: Start of the current billing period as a Unix ms timestamp (UTC calendar-month boundary).
  - `entityGroups` object[], required
    - `creditsUsed` number, required: Credits the entity group consumed in the current billing period. `0` when it has no usage yet.
    - `entity` string, required: The embed entity's identifier (the SSO `entity` value).

## Other responses

- `400`: Invalid request. Common causes: an empty `entities` array, more than 1000 `entities`, or a duplicated entity.
- `401`: Missing or invalid API key.
- `403`: Insufficient permissions.
- `404`: An entity has no entity group in the organization; the response names the first invalid entity.

## Changes

- **2026-11-03** `43290040f88f`: 1 info
  - endpoint added

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

---

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