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

# Read individual entity groups' AI credit usage

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

Read individual embed entity groups' AI credit usage for the current billing period. Names the entity groups by their embed `entity` string; each must have an entity group in the organization. Returns each entity group's credits used (summed across every member sharing that entity string), in request order, plus the billing-period bounds. An entity with no usage yet reports 0. At most 1000 entities per request; each entity may appear at most once. An unknown entity fails the whole request with a 404 naming it. This is a read, so it works even when credit-controls editing is disabled; it requires the same add/remove-users permission and embed-entity credit-limit feature flag as the per-entity-group limit endpoints.

## Request body

- AiCreditUsageEntityGroupsBody
  - `entities` string[], required — Entity groups to read usage for, at most 1000 per request. Each entry is an embed `entity` string.

## Response `200`

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

- AiCreditUsageEntityGroupsResponse
  - `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 id 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, or per-entity-group AI credit limits are not enabled for the organization.
- `404` — An entity has no entity group in the organization; the response names the first invalid entity.

---

[API](https://skmtc.net/omniapp/apis/omni-api.md) · [All operations](https://skmtc.net/omniapp/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omniapp/omni-api/revisions/de7cac8b5983/schema)