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

GET https://tokonomics.ca/analytics/events

Query Parameters

limit · integer · default: "50"

The maximum number of events to return per page. Must be between 1 and 200. Defaults to 50.

GET /analytics/events?limit=100

offset · 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.

GET /analytics/events?limit=50&offset=50

Response Fields

events · array

An array of UsageEvent objects, ordered from most recent to oldest.

Show UsageEvent fields

id · string

Unique UUID identifier for the event. Example: "3f6a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c"

model · string

The model name. Example: "gpt-4o"

provider · string

The provider slug. Example: "openai"

input_tokens · integer

Number of input (prompt) tokens consumed.

output_tokens · integer

Number of output (completion) tokens generated.

cache_read_tokens · integer

Number of tokens served from the provider’s prompt cache (billed at reduced rate where supported).

cache_creation_tokens · integer

Number of tokens written to the provider’s prompt cache (billed at premium where supported).

cost_usd · number

Total cost of the request in USD, calculated to 8 decimal places. Example: 0.00342100

latency_ms · integer

End-to-end request latency in milliseconds. Example: 843

tags · object

Custom key-value tags attached via X-Metering-Tags. Example: {"team": "growth", "feature": "summarizer"}

created_at · string

ISO 8601 datetime when the event was recorded. Example: "2026-06-10T14:32:01.000Z"

total · integer

The total number of events matching the query (before pagination). Use this with limit and offset to determine how many pages exist.

limit · integer

The limit value that was applied to this response.

offset · integer

The offset value that was applied to this response.

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.

Example

Request

curl "https://tokonomics.ca/analytics/events?limit=2&offset=0" \
  -H "Authorization: Bearer mk_your_key"

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