Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
period
string
default:"daily"
Aggregation period for usage records.Allowed values: hourly, daily, weekly, monthly
​
start_date
string
Start of the date range (inclusive). ISO 8601 date format: YYYY-MM-DD.
​
end_date
string
End of the date range (inclusive). ISO 8601 date format: YYYY-MM-DD.
​
user_id
string
Filter results to a single user by their UUID.
​
model
string
Filter results to a specific model name (e.g., gpt-4, claude-3-opus).
​
cursor
string
Opaque pagination cursor. Pass next_cursor from the previous response. Omit for the first page.
​
limit
integer
default:"25"
Items per page. Min 1, max 100.

​
Response

Returns a paginated envelope where each item is a UsageSummary object.
​
items
UsageSummary[]
required
Array of usage records for the requested period and filters.
​
next_cursor
string | null
required
Cursor to pass on the next request. null on the last page.
​
has_more
boolean
required
true if more pages exist.
​
total_count
integer
Total number of matching records.

​
Examples

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"
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

StatusErrorDescription
401unauthorizedInvalid or expired token
429rate_limitedRate limit exceeded