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 Build 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.
GET/v1/headless/usage/allowances
Get client AI allowances Build 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.
GET/v1/headless/usage/client/{identifier}
Path parameters
Field
Description
Options
identifier
Your stable client identifier
—
Update client AI caps Build 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. 0 is rejected; it is not a cap.
PUT/v1/headless/usage/client/{identifier}
Path parameters
Field
Description
Options
identifier
Your stable client identifier
—
Body parameters
Field
Type
Required
Desc
Options
narrationUsageLimit
string | integer | null
No
Characters per month; null = no cap. Zero stops narration generation.
—
imageUsageLimit
string | integer | null
No
Image generations per month; null = no cap. Zero stops image generation.
—
Get default AI caps for new clients Build and above
Use this endpoint to read the workspace default narration and image caps that new clients pick up at create time. Limits serialize as a number or unlimited when there is no cap. Changing these defaults does not change existing clients. The response includes mismatched, a count of existing clients whose narration or image cap differs from these defaults.
GET/v1/headless/usage/client-defaults
Update default AI caps for new clients Build and above
Use this endpoint to set the workspace default narration and image caps for newly created clients. Send only the fields you want to change. Send null for no cap. 0 is rejected; it is not a cap. Existing clients are not changed. The response includes the same mismatched count as GET, recomputed against the saved defaults.
PUT/v1/headless/usage/client-defaults
Body parameters
Field
Type
Required
Desc
Options
clientCapsEnabled
boolean
No
—
narrationUsageLimit
string | integer | null
No
—
imageUsageLimit
string | integer | null
No
—
Apply default AI caps to existing clients Build and above
Use this endpoint to overwrite every existing client's narration and image caps with the current workspace defaults, including caps the partner set on individual clients. The response is updated (clients whose caps actually changed) and mismatched (clients that still differ; 0 after a successful apply).
POST/v1/headless/usage/client-defaults/apply
Get client usage Build 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.