On this page
aiUsage
query · in the family Billing and the wallet
What it does
Your group’s AI usage by day — calls, tokens, and spend, with a per-surface breakdown.
YOUR group's AI usage by UTC day: composed off the daily rollup rows the meter grows with EVERY metered call (calls · tokens · nano-exact spend + the per-surface split), ≤ 92 bounded point-reads — never a scan. SELF-group BY CONSTRUCTION (no target arg exists — the tokenEntries stance); days defaults 30, clamps 1..92; only days WITH usage answer (an empty window is the honest answer). costUsd values are decimal strings (the money-string law). Requires authentication.
What happens
A read over the running usage counters the platform keeps for every AI call; money shows in exact USD. Only days with usage appear.
Who may call it
Capability area: Billing and the wallet — Your platform bill, token purchases and the usage and cost reads.
- Owner
- Manager
- Associate Manager
- An API key whose scope allows
api:aiUsage
Arguments
| Name | Type | Required | Notes |
|---|---|---|---|
days | Int | no | No further notes. |
Returns
AiUsageWindow AiUsageWindow! — YOUR group's AI-usage window: the days WITH usage, newest first, + the window totals.
Example request
query ExampleAiUsage($days: Int) {
aiUsage(days: $days) {
totalCalls
totalTokensInput
totalTokensOutput
totalCostUsd
}
}Variables:
{
"days": 1
}Example response
{
"data": {
"aiUsage": {
"totalCalls": 1,
"totalTokensInput": 1,
"totalTokensOutput": 1,
"totalCostUsd": "<total cost usd>"
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": null,
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}Errors this call can answer
VALIDATION/INVALID— Something in the request is not valid. (VALIDATION)AUTHN/REQUIRED— Sign in to do this. (AUTHN)AUTHZ/FORBIDDEN— Your role does not allow this action. (AUTHZ)RATE_LIMIT/THROTTLED— Too many requests in a short time. (RATE_LIMIT)