GET /v1/usage

Pull usage_events aggregations for an arbitrary window. Returns total cost, per-endpoint / per-provider / per-mode breakdowns, and a time series of buckets. Use this to power billing dashboards or to alert on spend deltas.

GET/v1/usage— Aggregate usage for a window

Pricing — free

No charge. No rate limit. Reads from the same usage_events table that powers your dashboard.

Quickstart

bash

curl "https://api.mentionsapi.com/v1/usage?granularity=day&since=2026-04-01" \
  -H "Authorization: Bearer lvk_live_..."

Query parameters

Field	Type	Description
`since`optional	`string (ISO 8601)`	Start of the window. Defaults to 30 days ago.
`until`optional	`string (ISO 8601)`	End of the window. Defaults to now.
`granularity`optional	`string`	'total' \| 'day' \| 'hour'. 'total' returns just the total block; the others populate `series[]`. Default: 'total'.
`endpoint`optional	`string`	Filter to a single endpoint, e.g. '/v1/check'.
`mode`optional	`string`	Filter to a single mode, e.g. 'quick' or 'perplexity_live'.

Common gotcha: the granularity enum value is day, not daily. Sending daily returns a 400 with the valid options enumerated.

Response

json

{
  "request_id": "req_01JBQ2K8H...",
  "since": "2026-04-01T00:00:00Z",
  "until": "2026-04-25T12:00:00Z",
  "granularity": "day",
  "total": {
    "calls": 1248,
    "cost_cents": 4892,
    "cost_cents_by_endpoint": {
      "/v1/check": 4256,
      "/v1/discover": 600,
      "/v1/compare": 36
    },
    "cost_cents_by_provider": {
      "openai": 1064,
      "anthropic": 1064,
      "gemini": 1064,
      "perplexity": 1064,
      "internal": 636
    },
    "cost_cents_by_mode": {
      "quick": 2492,
      "perplexity_live": 1764,
      "discover": 600,
      "compare": 36
    }
  },
  "series": [
    { "bucket": "2026-04-01T00:00:00Z", "calls": 38, "cost_cents": 152 },
    { "bucket": "2026-04-02T00:00:00Z", "calls": 41, "cost_cents": 168 }
  ]
}

The total.cost_cents is always equal to sum(series[].cost_cents), and to the sum of each by-* breakdown. Per-provider cost is split evenly across providers that participated in a call (so single-provider mode:perplexity_live cost lands entirely on the Perplexity bucket, while a 4-provider mode:quick call splits 25% each).