Usage

Overview

Usage endpoints aggregate metered Agent activity into bounded UTC ranges. Use them to monitor Tenant totals or narrow reporting to an Agent, Session, or attribution value.

Endpoints

GET /v1/usage

Reads the daily usage rollups. The default range is the last 30 days ending today in UTC; custom ranges may span at most 31 days.

Request

Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.

Query parameter	Type	Default	Description
`from`, `to`	`YYYY-MM-DD`	last 30 days	Supply both or neither
`agentId`	string	—	Agent filter
`sessionId`	string	—	Session filter; `""` means stateless turns
`userId`	string	—	Attribution filter; `""` means tenant-level
`groupBy`	string	`day`	`day`, `agent`, `model`, `session`, or `user`
`limit`	integer	50	1–200; top-N only for `groupBy=session`

Response

Returns 200 OK with usage buckets and totals.

Response schema: usageResponseSchema.

{
  "buckets": [
    {
      "day": "2026-07-10",
      "agentId": null,
      "sessionId": null,
      "userId": null,
      "provider": null,
      "model": null,
      "inputTokens": 120,
      "outputTokens": 80,
      "requestCount": 2,
      "durationMs": 1400
    }
  ],
  "totals": {
    "inputTokens": 120,
    "outputTokens": 80,
    "requestCount": 2,
    "durationMs": 1400
  }
}

Errors

400 invalid_request for a partial/reversed/oversized range, invalid filter, group, or limit. See REST errors.

cURL

curl --get "$BLAZING_AGENTS_BASE_URL/v1/usage" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --data-urlencode "from=2026-07-01" \
  --data-urlencode "to=2026-07-10" \
  --data-urlencode "groupBy=day"

SDK: get. See Usage and quotas and Monitor usage and quotas.

GET /v1/agents/:agentId/usage

Returns the same aggregation as tenant usage, scoped to the Agent path parameter. A query-string agentId is ignored because the path wins.

Requires bearer authentication and an ag_… agentId path parameter. It accepts from, to, sessionId, userId, groupBy, and limit exactly as Get tenant usage. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.
Path	`agentId`	yes	Agent ID (`ag_…`).

curl --get \
  "$BLAZING_AGENTS_BASE_URL/v1/agents/ag_1234567890ABCDEF/usage" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --data-urlencode "groupBy=model"

SDK: get-for-agent. See Usage and quotas and Monitor usage and quotas.

On this page