> ## 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.

# Usage

> Query aggregated LLM usage data by user, model, and time period.

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

<ParamField query="period" type="string" default="daily">
  Aggregation period for usage records.

  Allowed values: `hourly`, `daily`, `weekly`, `monthly`
</ParamField>

<ParamField query="start_date" type="string">
  Start of the date range (inclusive). ISO 8601 date format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="end_date" type="string">
  End of the date range (inclusive). ISO 8601 date format: `YYYY-MM-DD`.
</ParamField>

<ParamField query="user_id" type="string">
  Filter results to a single user by their UUID.
</ParamField>

<ParamField query="model" type="string">
  Filter results to a specific model name (e.g., `gpt-4`, `claude-3-opus`).
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor. Pass `next_cursor` from the previous response. Omit for the first page.
</ParamField>

<ParamField query="limit" type="integer" default="25">
  Items per page. Min `1`, max `100`.
</ParamField>

### Response

Returns a [paginated envelope](/api/pagination) where each item is a `UsageSummary` object.

<ResponseField name="items" type="UsageSummary[]" required>
  Array of usage records for the requested period and filters.

  <Expandable title="UsageSummary fields">
    <ResponseField name="user_id" type="string" required>
      UUID of the user who made the requests.
    </ResponseField>

    <ResponseField name="user_email" type="string">
      Email address of the user.
    </ResponseField>

    <ResponseField name="model" type="string" required>
      LLM model name (e.g., `gpt-4`, `claude-3-sonnet-20240229`).
    </ResponseField>

    <ResponseField name="provider" type="string" required>
      LLM provider (e.g., `openai`, `anthropic`, `google`).
    </ResponseField>

    <ResponseField name="period" type="string" required>
      The aggregation period label. For `daily`, this is the date in `YYYY-MM-DD` format.
    </ResponseField>

    <ResponseField name="total_requests" type="integer" required>
      Total number of LLM requests in the period.
    </ResponseField>

    <ResponseField name="total_input_tokens" type="integer" required>
      Total input (prompt) tokens consumed.
    </ResponseField>

    <ResponseField name="total_output_tokens" type="integer" required>
      Total output (completion) tokens generated.
    </ResponseField>

    <ResponseField name="estimated_cost_usd" type="number" required>
      Estimated cost in USD based on provider pricing.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="next_cursor" type="string | null" required>
  Cursor to pass on the next request. `null` on the last page.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  `true` if more pages exist.
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of matching records.
</ResponseField>

### Examples

<CodeGroup>
  ```bash Fetch daily usage theme={null}
  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"
  ```

  ```bash Filter by user theme={null}
  curl "https://api.toktra.io/v1/usage?user_id=a1b2c3d4-0000-0000-0000-000000000001&period=monthly" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash Filter by model theme={null}
  curl "https://api.toktra.io/v1/usage?model=gpt-4&period=weekly&limit=50" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "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      |