API reference — Usage analytics

The usage analytics endpoint aggregates request data from the platform’s usage_records table. It supports configurable time bucketing (day/week/month), model filtering, and per-user cost rankings. Admin access is required.

Base path: GET /api/usage/analytics

Authentication: Authorization: Bearer arb_live_<admin-key>

Schemas

AnalyticsResponse

The top-level response object.

Field	Type	Description
`time_series`	TimeSeriesPoint[]	Time-bucketed usage data for the requested period
`by_model`	ModelBreakdown[]	Aggregated usage per model for the requested period
`top_users`	TopUser[]	Users ranked by total cost (descending)

TimeSeriesPoint

One entry per time bucket in the requested aggregation period.

Field	Type	Description
`period`	string	Period label — `"2026-03-12"` (day), `"2026-W11"` (week), `"2026-03"` (month)
`input_tokens`	integer	Total input tokens processed in this period
`output_tokens`	integer	Total output tokens generated in this period
`cost`	float	Estimated total cost (USD) in this period
`request_count`	integer	Number of AI requests in this period

ModelBreakdown

Field	Type	Description
`model_id`	string	Model identifier
`provider`	string	Provider name
`input_tokens`	integer	Total input tokens for this model
`output_tokens`	integer	Total output tokens for this model
`cost`	float	Total estimated cost (USD) for this model
`request_count`	integer	Number of requests to this model

TopUser

Field	Type	Description
`user_id`	string	User UUID
`username`	string	User display name
`total_cost`	float	Total cost attributed to this user (USD)
`request_count`	integer	Total requests by this user

Endpoint

Get usage analytics

GET /api/usage/analytics

Returns aggregated usage analytics for the admin dashboard. Admin role required.

Query parameters:

Parameter	Type	Default	Description
`date_from`	date (YYYY-MM-DD)	—	Start date inclusive (optional)
`date_to`	date (YYYY-MM-DD)	—	End date inclusive (optional)
`aggregation`	string	`day`	Time bucketing: `day`, `week`, or `month`
`model_id`	string	—	Filter results to a specific model ID (optional)

Request — last 30 days, daily bucketing:

GET /api/usage/analytics?date_from=2026-02-11&date_to=2026-03-12&aggregation=day
Authorization: Bearer arb_live_your-admin-key

Response (200):

{
  "time_series": [
    {
      "period": "2026-03-10",
      "input_tokens": 4250000,
      "output_tokens": 820000,
      "cost": 18.42,
      "request_count": 1240
    },
    {
      "period": "2026-03-11",
      "input_tokens": 5100000,
      "output_tokens": 960000,
      "cost": 22.18,
      "request_count": 1480
    },
    {
      "period": "2026-03-12",
      "input_tokens": 2100000,
      "output_tokens": 410000,
      "cost": 9.32,
      "request_count": 620
    }
  ],
  "by_model": [
    {
      "model_id": "claude-3-5-sonnet-20241022",
      "provider": "anthropic",
      "input_tokens": 8200000,
      "output_tokens": 1540000,
      "cost": 34.50,
      "request_count": 2180
    },
    {
      "model_id": "gpt-4o-mini",
      "provider": "openai",
      "input_tokens": 3250000,
      "output_tokens": 650000,
      "cost": 15.42,
      "request_count": 1160
    }
  ],
  "top_users": [
    {
      "user_id": "7c8d9e0f-1234-5678-abcd-ef0123456789",
      "username": "alice",
      "total_cost": 14.20,
      "request_count": 820
    },
    {
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "username": "bob",
      "total_cost": 9.80,
      "request_count": 560
    }
  ]
}

Request — monthly aggregation for a specific model:

GET /api/usage/analytics?aggregation=month&model_id=claude-3-5-sonnet-20241022
Authorization: Bearer arb_live_your-admin-key

Error (403 Forbidden):

{ "detail": "Admin access required" }

Error (400 Bad Request):

{ "detail": "aggregation must be one of: day, week, month" }

Period label formats

Aggregation	Period label format	Example
`day`	`YYYY-MM-DD`	`2026-03-12`
`week`	`YYYY-WWW`	`2026-W11`
`month`	`YYYY-MM`	`2026-03`

The week label uses ISO week numbering (%W — week 00 for days before the first Monday of the year). Use the date_from / date_to filters to bound the response to a meaningful range.

Notes

Cost values are estimates based on the cost_per_input_token and cost_per_output_token values in the model catalog. If these fields are null for a model, cost will be 0.0 for that model’s rows.
top_users always covers the full requested date range, regardless of aggregation. It is not time-bucketed.
Empty periods — dates with no requests are not included in time_series. Gaps in the series indicate zero-activity periods.
If neither date_from nor date_to is specified, the query covers all historical data. For large deployments, always provide date bounds to avoid slow queries.