Skip to content

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.

billing_period
string
/^\d{4}-\d{2}$/

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.

The month’s usage, by provider.

AI provider calls recorded for one month, by provider.

object
billing_period
required

The month the report covers: the value sent, or the current month in UTC.

string
total_cost_usd_micros
required

The providers’ cost_usd_micros added together, in millionths of a dollar. Divide by 1,000,000 for dollars.

integer format: int64
providers
required

One entry for each provider with at least one recorded call in the month, sorted by name. Empty when there are none.

Array<object>

One provider’s calls in the month.

object
provider
required

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.

string
call_count
required

The number of successful calls.

integer format: int64
cost_usd_micros
required

The estimated cost of the successful calls, in millionths of a dollar. Calls with no stored cost count as 0.

integer format: int64
status_counts
required

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
key
additional properties
integer format: int64

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed