Docs menu

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.

KeyWorks onElsewhere
Management key cai_mgmt_<secret>/v1/organization/* only401 on model endpoints
API key cai_<secret>Model endpoints401 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

MethodPathReturns
GET/v1/organization/balancePAYG balance, promo grants and budget packs
GET/v1/organization/usageUsage per day, project, key and model
GET/v1/organization/requestsRequest metadata from the last 90 days, without content
GET/v1/organization/projectsProjects 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:

Endpointas_of means
/balance, /requests, /projectsThe time the data was read
/usageThe 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
FieldMeaning
payg_usdPay-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_usdTotal credited to that tier
packs[].official_value_up_to_usdWhat 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_totalSums over all packs; zero when you have none
available_for_model_usdOnly with ?model=: promo that covers the model, plus packs whose tier includes it, plus PAYG

Usage

Daily totals per project, key and model.

QueryTypeNotes
from, toISO date, UTCRequired; at most 366 days
project, key, modelstring, can repeatFilters
granularitydayOnly day
limitintDefault 100, maximum 1,000
cursorstringFrom 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.

QueryNotes
from, toISO dates, UTC; within the last 90 days
project, key, modelFilters
statusok, partial or error
limit, cursorDefault 100, maximum 1,000
status filterRows it returns
okHTTP status below 400 and the request finished
partialHTTP status below 400, but the request did not finish: the client disconnected, the stream was cut off, or it reached its maximum duration
errorHTTP 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.

StatusCodeWhen
400invalid_requestA query parameter is wrong, for example a range over 366 days
401invalid_api_keyThe key is wrong, revoked, or is an API key instead of a management key
429rate_limitedMore 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

  • modelstringoptional

    Public 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

  • fromstringrequired

  • tostringrequired

    At most 366 days after from.

  • projectstring[]optional

  • keystring[]optional

  • modelstring[]optional

  • granularitystringoptional

  • limitintegeroptional

  • cursorstringoptional

    Opaque 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

  • fromstringoptional

  • tostringoptional

  • projectstringoptional

  • keystringoptional

  • modelstringoptional

  • statusstringoptional

  • limitintegeroptional

  • cursorstringoptional

    Opaque 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.