GET /v1/usage Returns a cursor-paginated usage summary broken down by user, model, and time period. Use this endpoint to build reports, power dashboards, or feed data into external analytics systems.
GET https://api.toktra.io/v1/usage
Query parameters Aggregation period for usage records. Allowed values: hourly, daily, weekly, monthly
Start of the date range (inclusive). ISO 8601 date format: YYYY-MM-DD.
End of the date range (inclusive). ISO 8601 date format: YYYY-MM-DD.
Filter results to a single user by their UUID.
Filter results to a specific model name (e.g., gpt-4, claude-3-opus).
Opaque pagination cursor. Pass next_cursor from the previous response. Omit for the first page.
Items per page. Min 1, max 100.
Response Returns a paginated envelope where each item is a UsageSummary object.
Array of usage records for the requested period and filters. UUID of the user who made the requests.
Email address of the user.
LLM model name (e.g., gpt-4, claude-3-sonnet-20240229).
LLM provider (e.g., openai, anthropic, google).
The aggregation period label. For daily, this is the date in YYYY-MM-DD format.
Total number of LLM requests in the period.
Total input (prompt) tokens consumed.
Total output (completion) tokens generated.
Estimated cost in USD based on provider pricing.
Cursor to pass on the next request. null on the last page.
true if more pages exist.
Total number of matching records.
Examples Fetch daily usage
Filter by user
Filter by model
curl "https://api.toktra.io/v1/usage?period=daily&start_date=2025-01-01&end_date=2025-01-31" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl "https://api.toktra.io/v1/usage?user_id=a1b2c3d4-0000-0000-0000-000000000001&period=monthly" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl "https://api.toktra.io/v1/usage?model=gpt-4&period=weekly&limit=50" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response { "items" : [ { "user_id" : "a1b2c3d4-0000-0000-0000-000000000001" , "user_email" : "alice@acme.com" , "model" : "gpt-4" , "provider" : "openai" , "period" : "2025-01-15" , "total_requests" : 247 , "total_input_tokens" : 185000 , "total_output_tokens" : 92500 , "estimated_cost_usd" : 8.32 }, { "user_id" : "a1b2c3d4-0000-0000-0000-000000000002" , "user_email" : "bob@acme.com" , "model" : "claude-3-opus-20240229" , "provider" : "anthropic" , "period" : "2025-01-15" , "total_requests" : 83 , "total_input_tokens" : 42000 , "total_output_tokens" : 18500 , "estimated_cost_usd" : 3.71 } ], "next_cursor" : "eyJpZCI6ImExYjJjM2Q0LTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMiJ9" , "has_more" : true , "total_count" : 312 }
Error responses Status Error Description 401unauthorizedInvalid or expired token 429rate_limitedRate limit exceeded