Get usage overview
Get a usage overview.
/v1/usage/overviewOverview
See how much your agents use: tokens, requests, and run time, added up over UTC date ranges of up to 31 days. Look at your whole tenant or narrow it to one agent, session, or end user.
Endpoints
Get usageGET/v1/usage
Get tenant usage.
Returns your tenant's token, request, and run-time totals for a UTC date range, split into buckets by groupBy. Send both from and to or neither; without them you get the last 30 days ending today, and to can be at most 31 days after from. The response is not paginated.
Request
Requires bearer authentication.
| Field | Type | Location | Required | Description |
|---|---|---|---|---|
from | string | query | First UTC day to include, as YYYY-MM-DD. Send it with to, or leave both out for the last 30 days ending today. | |
to | string | query | Last UTC day to include, as YYYY-MM-DD. It must not be before from and can be at most 31 days after it. | |
agentId | string | query | Return only usage by this agent. | |
sessionId | string | query | Return only usage in this session. Send an empty string for calls made without a session. | |
userId | string | query | Return only usage for this end user. Send an empty string for tenant-level usage. | |
groupBy | string | query | How to group the buckets: day, agent, model, session, or user. session returns the top sessions by total tokens; the others return every group. One of day, agent, model, session, user. Defaults to day. | |
limit | integer | query | Number of sessions to return with groupBy=session, from 1 to 200. Other groupings ignore it. 1–200. Defaults to 50. |
Response
The usage overview.
The usage overview.
Returns 200 OK as application/json. Usage buckets and totals.
Response schema: Usage.
{
"buckets": [
{
"day": "2026-07-09",
"agentId": null,
"sessionId": null,
"userId": null,
"provider": null,
"model": null,
"inputTokens": 18240,
"outputTokens": 6120,
"requestCount": 14,
"durationMs": 41300
},
{
"day": "2026-07-10",
"agentId": null,
"sessionId": null,
"userId": null,
"provider": null,
"model": null,
"inputTokens": 9600,
"outputTokens": 3050,
"requestCount": 8,
"durationMs": 22750
}
],
"totals": {
"inputTokens": 27840,
"outputTokens": 9170,
"requestCount": 22,
"durationMs": 64050
}
}Errors
| Status | Codes | Description |
|---|---|---|
400 | validation_failed | The request is invalid |
401 | unauthorized | The credential is missing or invalid |
402 | subscription_required | An active subscription or usage credit is required |
See REST errors for the error envelope and shared codes.
cURL
curl "$BLAZING_AGENTS_BASE_URL/v1/usage" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"Get usage overviewGET/v1/usage/overview
Get a usage overview.
Returns everything a usage dashboard needs in one response: totals, a daily series, and your top agents, users, and models. Send both from and to or neither; without them you get the last 30 days ending today, and to can be at most 31 days after from. daily has one entry for every day in the range, oldest first, including days with no usage. byAgent, byUser, and byModel are sorted by total tokens, highest first, and cut off at limit. byModel can add one bucket with provider and model set to null for the models left out, so its rows still add up to the totals. activeAgentCount counts every agent with usage in the range, not only those shown.
Request
Requires bearer authentication.
| Field | Type | Location | Required | Description |
|---|---|---|---|---|
from | string | query | First UTC day to include, as YYYY-MM-DD. Send it with to, or leave both out for the last 30 days ending today. | |
to | string | query | Last UTC day to include, as YYYY-MM-DD. It must not be before from and can be at most 31 days after it. | |
limit | integer | query | Rows to return in each ranked breakdown (byAgent, byUser, byModel), from 1 to 20. 1–20. Defaults to 5. |
Response
The usage overview.
The usage overview.
Returns 200 OK as application/json. The usage overview.
Response schema: UsageOverview.
{
"totals": {
"inputTokens": 27840,
"outputTokens": 9170,
"requestCount": 22,
"durationMs": 64050
},
"daily": [
{
"day": "2026-07-09",
"agentId": null,
"sessionId": null,
"userId": null,
"provider": null,
"model": null,
"inputTokens": 18240,
"outputTokens": 6120,
"requestCount": 14,
"durationMs": 41300
},
{
"day": "2026-07-10",
"agentId": null,
"sessionId": null,
"userId": null,
"provider": null,
"model": null,
"inputTokens": 9600,
"outputTokens": 3050,
"requestCount": 8,
"durationMs": 22750
}
],
"byAgent": [
{
"day": null,
"agentId": "ag_4kP9sT2vXq7LmN3a",
"sessionId": null,
"userId": null,
"provider": null,
"model": null,
"inputTokens": 27840,
"outputTokens": 9170,
"requestCount": 22,
"durationMs": 64050
}
],
"byUser": [
{
"day": null,
"agentId": null,
"sessionId": null,
"userId": "app:user-42",
"provider": null,
"model": null,
"inputTokens": 20100,
"outputTokens": 6800,
"requestCount": 15,
"durationMs": 45200
},
{
"day": null,
"agentId": null,
"sessionId": null,
"userId": "",
"provider": null,
"model": null,
"inputTokens": 7740,
"outputTokens": 2370,
"requestCount": 7,
"durationMs": 18850
}
],
"byModel": [
{
"day": null,
"agentId": null,
"sessionId": null,
"userId": null,
"provider": "openrouter",
"model": "openai/gpt-6-luna",
"inputTokens": 27840,
"outputTokens": 9170,
"requestCount": 22,
"durationMs": 64050
}
],
"activeAgentCount": 1
}Errors
| Status | Codes | Description |
|---|---|---|
400 | validation_failed | The request is invalid |
401 | unauthorized | The credential is missing or invalid |
402 | subscription_required | An active subscription or usage credit is required |
See REST errors for the error envelope and shared codes.
cURL
curl "$BLAZING_AGENTS_BASE_URL/v1/usage/overview" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"Get agent usageGET/v1/agents/:agentId/usage
Get agent usage.
Returns usage for one agent, with the same range rules, filters, and grouping as GET /v1/usage. An agentId in the query string is ignored. An agent with no usage, including one that does not exist, returns zero totals and no buckets.
Request
Requires bearer authentication.
| Field | Type | Location | Required | Description |
|---|---|---|---|---|
agentId | string | path | required | ID of the agent. |
from | string | query | First UTC day to include, as YYYY-MM-DD. Send it with to, or leave both out for the last 30 days ending today. | |
to | string | query | Last UTC day to include, as YYYY-MM-DD. It must not be before from and can be at most 31 days after it. | |
sessionId | string | query | Return only usage in this session. Send an empty string for calls made without a session. | |
userId | string | query | Return only usage for this end user. Send an empty string for tenant-level usage. | |
groupBy | string | query | How to group the buckets: day, agent, model, session, or user. session returns the top sessions by total tokens; the others return every group. One of day, agent, model, session, user. Defaults to day. | |
limit | integer | query | Number of sessions to return with groupBy=session, from 1 to 200. Other groupings ignore it. 1–200. Defaults to 50. |
Response
The usage overview.
The usage overview.
Returns 200 OK as application/json. Usage buckets and totals for the agent.
Response schema: Usage.
{
"buckets": [
{
"day": null,
"agentId": "ag_4kP9sT2vXq7LmN3a",
"sessionId": null,
"userId": null,
"provider": "openrouter",
"model": "openai/gpt-6-luna",
"inputTokens": 27840,
"outputTokens": 9170,
"requestCount": 22,
"durationMs": 64050
}
],
"totals": {
"inputTokens": 27840,
"outputTokens": 9170,
"requestCount": 22,
"durationMs": 64050
}
}Errors
| Status | Codes | Description |
|---|---|---|
400 | validation_failed | The request is invalid |
401 | unauthorized | The credential is missing or invalid |
402 | subscription_required | An active subscription or usage credit is required |
See REST errors for the error envelope and shared codes.
cURL
curl "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/usage" \
--header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"Next
- Usage and quotas to track spend and set a quota.
- Tenant API to change your quota.