Docs / API
Usage API
Read balance, daily usage, requests and projects with a management key through /v1/organization/*.
Last updated
Management keys
The Usage API reads your account data from your own server. It uses a management key, not an API key.
A management key looks like cai_mgmt_<secret>. Create one in Settings in the dashboard. It is shown once; Cent AI stores only a hash. You can revoke it there, and revocation takes effect within seconds.
| Key | Works on | Elsewhere |
|---|---|---|
Management key cai_mgmt_<secret> | /v1/organization/* only | 401 on model endpoints |
API key cai_<secret> | Model endpoints | 401 on /v1/organization/* |
Send the management key as a Bearer token:
GET https://api.cent-ai.dev/v1/organization/balance
Authorization: Bearer cai_mgmt_<secret>
The Usage API is read-only. A management key cannot call models, create keys or change budgets.
Endpoints
| Method | Path | Returns |
|---|---|---|
| GET | /v1/organization/balance | PAYG balance, promo grants and budget packs |
| GET | /v1/organization/usage | Usage per day, project, key and model |
| GET | /v1/organization/requests | Request metadata from the last 90 days, without content |
| GET | /v1/organization/projects | Projects with budgets and spend |
The paths follow the pattern of the OpenAI Admin API. The response shapes are Cent AI's own and are documented on this page.
Amounts are decimal strings with 9 fraction digits. Times are RFC 3339 in UTC.
Freshness: as_of
Every response has a top-level as_of field:
| Endpoint | as_of means |
|---|---|
/balance, /requests, /projects | The time the data was read |
/usage | The time up to which daily totals are complete; null before the first totals are ready |
Usage totals are built in the background, so the newest requests can appear in /requests before they appear in /usage. The numbers match the dashboard at the same time.
Balance
GET /v1/organization/balance
GET /v1/organization/balance?model=glm-5.3
| Field | Meaning |
|---|---|
payg_usd | Pay-as-you-go balance. It can be negative after a request that cost more than the balance |
promo[] | Promo grants that have not expired, with expires_at |
packs[] | One entry per budget pack tier you own. Packs do not expire |
packs[].credited_usd | Total credited to that tier |
packs[].official_value_up_to_usd | What the remaining pack is worth at official prices, for display only; not a balance. null when no model in the tier has an official rate |
packs_total | Sums over all packs; zero when you have none |
available_for_model_usd | Only with ?model=: promo that covers the model, plus packs whose tier includes it, plus PAYG |
Usage
Daily totals per project, key and model.
| Query | Type | Notes |
|---|---|---|
from, to | ISO date, UTC | Required; at most 366 days |
project, key, model | string, can repeat | Filters |
granularity | day | Only day |
limit | int | Default 100, maximum 1,000 |
cursor | string | From next_cursor of the previous page |
curl "https://api.cent-ai.dev/v1/organization/usage?from=2026-10-01&to=2026-10-31&model=glm-5.3" \
-H "Authorization: Bearer $CENT_AI_MGMT_KEY"
The sum of all rows equals the CSV export of the Usage page in the dashboard for the same filters.
Requests
One row per request: metadata only, never the prompt or the response.
| Query | Notes |
|---|---|
from, to | ISO dates, UTC; within the last 90 days |
project, key, model | Filters |
status | ok, partial or error |
limit, cursor | Default 100, maximum 1,000 |
status filter | Rows it returns |
|---|---|
ok | HTTP status below 400 and the request finished |
partial | HTTP status below 400, but the request did not finish: the client disconnected, the stream was cut off, or it reached its maximum duration |
error | HTTP status 400 or higher |
curl "https://api.cent-ai.dev/v1/organization/requests?status=error&limit=50" \
-H "Authorization: Bearer $CENT_AI_MGMT_KEY"
In a row, status is the HTTP status of the request. request_id is the same ID as the x-request-id response header and the Requests page. estimated: true means the token counts are an estimate because the model did not report usage.
To read every page, repeat the call with cursor set to next_cursor until has_more is false.
Projects
curl https://api.cent-ai.dev/v1/organization/projects \
-H "Authorization: Bearer $CENT_AI_MGMT_KEY"
A null budget means no budget. See Projects and budgets.
Limits and errors
Each management key can make 60 requests per minute.
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A query parameter is wrong, for example a range over 366 days |
| 401 | invalid_api_key | The key is wrong, revoked, or is an API key instead of a management key |
| 429 | rate_limited | More than 60 requests per minute; wait for Retry-After |
Call it from your server
/v1/organization/* sends no CORS headers, so browsers block calls from web pages. Call it from your server and keep the management key there.
Contract
GET/v1/organization/balance
Balance
Auth · Management key
Query parameters
modelstringoptionalPublic model name; adds available_for_model_usd.
Responses
- 200Balance by source.
- 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.retry
Response headers
Retry-Afterx-request-id
GET/v1/organization/usage
Daily usage
Auth · Management key
Query parameters
fromstringrequiredtostringrequiredAt most 366 days after from.
projectstring[]optionalkeystring[]optionalmodelstring[]optionalgranularitystringoptionallimitintegeroptionalcursorstringoptionalOpaque cursor from next_cursor.
Responses
- 200Rows per day, project, key and model.
- 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.retry
Response headers
Retry-Afterx-request-id
GET/v1/organization/requests
Requests of the last 90 days
Auth · Management key
Query parameters
fromstringoptionaltostringoptionalprojectstringoptionalkeystringoptionalmodelstringoptionalstatusstringoptionallimitintegeroptionalcursorstringoptionalOpaque cursor from next_cursor.
Responses
- 200Request metadata without content.
- 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.retry
Response headers
Retry-Afterx-request-id
GET/v1/organization/projects
Projects with budgets and spend
Auth · Management key
Responses
- 200Projects.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.retry
Response headers
Retry-Afterx-request-id
Generated from the OpenAPI contract.