Usage
Usage endpoints let you inspect workspace allowances, review per-client consumption, and manage client-level AI caps. Usage metrics include identified recipients, anonymous recipients, narration tokens, and image generations.
Get workspace allowances Embed Core and above
Use this endpoint to get the current billing-period allowances and usage totals for your workspace. The response includes ir, ar, narrationUsage, and imageUsage rows.
/v1/headless/usage/allowancesGet client AI allowances Embed Automate and above
Use this endpoint to get the current monthly AI allowance rows for a client identifier. Client AI allowance rows include narration token usage and image generation usage.
/v1/headless/usage/client/{identifier}Path parameters
| Field | Description | Options |
|---|---|---|
identifier | Your stable client identifier | — |
Update client AI caps Embed Automate and above
Use this endpoint to set client-level monthly caps for narration tokens and image generations. Send null for a cap to make that client unlimited for the metric.
/v1/headless/usage/client/{identifier}Path parameters
| Field | Description | Options |
|---|---|---|
identifier | Your stable client identifier | — |
Body parameters
| Field | Type | Required | Desc | Options |
|---|---|---|---|---|
narrationUsageLimit | number | null | No | Tokens per month; null = unlimited | — |
imageUsageLimit | number | null | No | Image generations per month; null = unlimited | — |
Get client usage Embed Automate and above
Use this endpoint to fetch paginated usage rows for each client identifier in your workspace. You can provide a usage window with start and end; date ranges can be up to 366 days.
/v1/headless/usage/clientsQuery parameters
| Field | Type | Required | Default | Description | Options |
|---|---|---|---|---|---|
start | string | No | — | — | |
end | string | No | — | — | |
page | number | No | 0 | — | |
length | number | No | 50 | — |