> ## Documentation Index
> Fetch the complete documentation index at: https://tokonomics.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /analytics/events — Paginated Raw Usage Events

> Returns paginated raw usage event records with full token counts, cost, latency, model, provider, and custom tags for every LLM call.

The events endpoint gives you access to the raw, per-request usage records that power all of Tokonomics' analytics. Each record contains the full token breakdown, precise cost in USD, end-to-end latency, provider, model, and any custom tags you attached. Use it to build custom reports, audit specific requests, or export data into your own data warehouse.

**Endpoint**

```text theme={null}
GET https://tokonomics.ca/analytics/events
```

## Query Parameters

<ParamField query="limit" type="integer" default="50">
  The maximum number of events to return per page. Must be between `1` and `200`. Defaults to `50`.

  ```text theme={null}
  GET /analytics/events?limit=100
  ```
</ParamField>

<ParamField query="offset" type="integer" default="0">
  The number of events to skip before returning results. Use this together with `limit` to paginate through large result sets. Defaults to `0`.

  ```text theme={null}
  GET /analytics/events?limit=50&offset=50
  ```
</ParamField>

## Response Fields

<ResponseField name="events" type="array">
  An array of `UsageEvent` objects, ordered from most recent to oldest.

  <Expandable title="UsageEvent fields">
    <ResponseField name="id" type="string">
      Unique UUID identifier for the event. Example: `"3f6a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"`
    </ResponseField>

    <ResponseField name="model" type="string">
      The model name. Example: `"gpt-4o"`
    </ResponseField>

    <ResponseField name="provider" type="string">
      The provider slug. Example: `"openai"`
    </ResponseField>

    <ResponseField name="input_tokens" type="integer">
      Number of input (prompt) tokens consumed.
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      Number of output (completion) tokens generated.
    </ResponseField>

    <ResponseField name="cache_read_tokens" type="integer">
      Number of tokens served from the provider's prompt cache (billed at reduced rate where supported).
    </ResponseField>

    <ResponseField name="cache_creation_tokens" type="integer">
      Number of tokens written to the provider's prompt cache (billed at premium where supported).
    </ResponseField>

    <ResponseField name="cost_usd" type="number">
      Total cost of the request in USD, calculated to 8 decimal places. Example: `0.00342100`
    </ResponseField>

    <ResponseField name="latency_ms" type="integer">
      End-to-end request latency in milliseconds. Example: `843`
    </ResponseField>

    <ResponseField name="tags" type="object">
      Custom key-value tags attached via `X-Metering-Tags`. Example: `{"team": "growth", "feature": "summarizer"}`
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 datetime when the event was recorded. Example: `"2026-06-10T14:32:01.000Z"`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  The total number of events matching the query (before pagination). Use this with `limit` and `offset` to determine how many pages exist.
</ResponseField>

<ResponseField name="limit" type="integer">
  The `limit` value that was applied to this response.
</ResponseField>

<ResponseField name="offset" type="integer">
  The `offset` value that was applied to this response.
</ResponseField>

<Tip>
  To paginate through all events, increment `offset` by `limit` on each request until `offset >= total`. For example, if `total` is `340` and you're using `limit=100`, you'll need 4 requests with offsets `0`, `100`, `200`, and `300`. The maximum page size is `200`.
</Tip>

## Example

<CodeGroup>
  ```bash Request theme={null}
  curl "https://tokonomics.ca/analytics/events?limit=2&offset=0" \
    -H "Authorization: Bearer mk_your_key"
  ```

  ```json Response theme={null}
  {
    "events": [
      {
        "id": "3f6a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
        "model": "gpt-4o",
        "provider": "openai",
        "input_tokens": 512,
        "output_tokens": 128,
        "cache_read_tokens": 0,
        "cache_creation_tokens": 0,
        "cost_usd": 0.00342100,
        "latency_ms": 843,
        "tags": {"team": "growth", "feature": "summarizer"},
        "created_at": "2026-06-10T14:32:01.000Z"
      },
      {
        "id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
        "model": "claude-opus-4-5",
        "provider": "anthropic",
        "input_tokens": 1024,
        "output_tokens": 256,
        "cache_read_tokens": 512,
        "cache_creation_tokens": 0,
        "cost_usd": 0.01920000,
        "latency_ms": 1204,
        "tags": {"team": "support", "tenant_id": "acme-corp"},
        "created_at": "2026-06-10T14:28:44.000Z"
      }
    ],
    "total": 5620,
    "limit": 2,
    "offset": 0
  }
  ```
</CodeGroup>