Usage

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

string

default:"daily"

Aggregation period for usage records.Allowed values: hourly, daily, weekly, monthly

string

Start of the date range (inclusive). ISO 8601 date format: YYYY-MM-DD.

string

End of the date range (inclusive). ISO 8601 date format: YYYY-MM-DD.

string

Filter results to a single user by their UUID.

string

Filter results to a specific model name (e.g., gpt-4, claude-3-opus).

string

Opaque pagination cursor. Pass next_cursor from the previous response. Omit for the first page.

integer

default:"25"

Items per page. Min 1, max 100.

Response

Returns a paginated envelope where each item is a UsageSummary object.

UsageSummary[]

required

Array of usage records for the requested period and filters.

Show UsageSummary fields

string

required

UUID of the user who made the requests.

string

Email address of the user.

string

required

LLM model name (e.g., gpt-4, claude-3-sonnet-20240229).

string

required

LLM provider (e.g., openai, anthropic, google).

string

required

The aggregation period label. For daily, this is the date in YYYY-MM-DD format.

integer

required

Total number of LLM requests in the period.

integer

required

Total input (prompt) tokens consumed.

integer

required

Total output (completion) tokens generated.

number

required

Estimated cost in USD based on provider pricing.

string | null

required

Cursor to pass on the next request. null on the last page.

boolean

required

true if more pages exist.

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"

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
`401`	`unauthorized`	Invalid or expired token
`429`	`rate_limited`	Rate limit exceeded

Overview

Endpoints

GET /v1/usage

Query parameters

Response

Examples

Error responses

​GET /v1/usage

​Query parameters

​Response

​Examples

​Error responses

GET /v1/usage

Query parameters

Response

Examples

Error responses