Skip to main content
GET
/
api
/
v1
/
usage
Get Usage
curl --request GET \
  --url https://api.example.com/api/v1/usage
Retrieve usage analytics including request counts, token consumption, cost breakdown by mode/model, and latency percentiles.

​
Authentication

Requires a Bearer token. See Authentication.

​
Query Parameters

​
from
string
Start date (ISO 8601, e.g., "2026-04-01").
​
to
string
End date (ISO 8601, e.g., "2026-04-14").
​
scope
string
"user" (default when outside a team) or "org" (default when inside a team). When "org", the response reflects the team’s shared credit pool, transactions across every member, and the actor’s display name / email on each row. Requires the viewUsage permission in the active team.

​
Request Examples

curl "https://www.hitheo.ai/api/v1/usage?from=2026-04-01&to=2026-04-14&scope=org" \
  -H "Authorization: Bearer $THEO_API_KEY"

​
Response

Returns usage data including:
  • Total requests by day/week/month
  • Cost breakdown by mode, model, and skill
  • Model distribution — which engines handled your requests
  • Latency percentiles — p50, p95, p99 response times
  • Cache hit rate — percentage of requests served from semantic cache

​
Endpoint

GET /api/v1/usage Requires authentication via Bearer token. See Authentication.