Read AI usage and costs for a month
GET /admin/ai/usage
Returns the AI provider calls recorded for one month, by provider: how many succeeded, their estimated cost, and how many ended each way.
You need ai.admin or system.admin for the whole install; a
permission held only for a team doesn’t count. Without one you get
403, and signed-out callers get 401. A repeated billing_period
gets a plain-text 400, even when you aren’t signed in.
Leave billing_period out, or send it empty, for the current month
in UTC. Any other value is used as sent: a call counts when its
month, written YYYY-MM in the database’s time zone, is exactly
that value, so a value in another format just gives an empty report.
call_count and cost_usd_micros cover successful calls only,
while status_counts covers every recorded call, so a provider
whose calls all failed is listed with a call_count of 0. Costs are
the estimates stored with each call, in millionths of a dollar; a
call with no stored cost counts as 0, and none of this is a
provider’s bill.
Only calls that left a record are counted. clip_local and
whisper_local record only their successful calls, and calls
refused before reaching a provider, for budget or privacy, aren’t
recorded unless they were MCP tool calls. Records are written on a
best-effort basis, so some calls can be missing.
Providers are sorted by name, with no paging. The two parts of the report are read separately, so a call recorded in between can show up in one and not the other. Server errors get a plain-text 500.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”The month to report, as YYYY-MM, such as 2026-11. Leave it out
or empty for the current month in UTC. The format isn’t checked; a
value that matches no month gives an empty report.
Responses
Section titled “ Responses ”The month’s usage, by provider.
AI provider calls recorded for one month, by provider.
object
The month the report covers: the value sent, or the current month in UTC.
The providers’ cost_usd_micros added together, in millionths of a dollar. Divide by 1,000,000 for dollars.
One entry for each provider with at least one recorded call in the month, sorted by name. Empty when there are none.
One provider’s calls in the month.
object
The provider name stored with each call. For MCP tool calls it’s the MCP server’s name. It isn’t matched against the current settings, so a provider no longer in use still appears.
The number of successful calls.
The estimated cost of the successful calls, in millionths of a dollar. Calls with no stored cost count as 0.
How many recorded calls ended each way, keyed by outcome: success,
rate_limited, transient_error, permanent_error,
budget_blocked or privacy_blocked. Outcomes with no calls are
left out.
object
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completed