GET /v1/usage

Programmatic read of your usage events over an arbitrary window. Useful for in-app meters, invoicing reconciliation, and overage warnings.

Legacy endpoint. This documents an older surface kept for back-compat with existing integrations. New integrations should use /docs/api/usage instead — see the quickstart for the modern API.

GET/v1/usage— Read usage events for a window

Query parameters

Field	Type	Description
`start`optional	`string (ISO 8601 datetime)`	Window start. Defaults to 30 days ago if omitted. Must be strictly before end.
`end`optional	`string (ISO 8601 datetime)`	Window end. Defaults to now if omitted.
`granularity`optional	`'day' \| 'hour' \| 'total'`	Time-bucket size. "total" collapses everything into a single bucket; "hour" and "day" return a time series. Default: `'day'`

Example request

bash

curl "https://api.mentionsapi.com/v1/usage?granularity=day&start=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer $MENTIONSAPI_KEY"

Response

Field	Type	Description
`request_id`optional	`string`	Unique id for this read call.
`account_id`optional	`string`	Your account UUID.
`plan`optional	`string`	Your current plan identifier (e.g. 'free', 'growth').
`window`optional	`{ start, end, granularity }`	Echo of the resolved window — defaults filled in. Both timestamps are ISO 8601.
`total`optional	`UsageBucket`	Rolled-up counts across the whole window. See the UsageBucket shape below.
`series`optional	`Array<{ bucket: string } & UsageBucket>`	Per-bucket breakdown in ascending order by bucket key. Empty when granularity is "total" (the total field holds everything).
`monthly_quota`optional	`number \| null`	Your plan's soft monthly call quota if one is configured, otherwise null.

Top-level fields

UsageBucket

Field	Type	Description
`requests`optional	`number`	Total calls in the bucket (including cache hits and errors).
`billable_units`optional	`number`	Sum of billable_units recorded per call. Typically equals the number of successful provider calls in the window.
`cache_hits`optional	`number`	How many calls were served from L1/L2/L3 cache.
`errors`optional	`number`	Number of calls that returned a 4xx or 5xx status.
`provider_breakdown`optional	`Record<ProviderId, number>`	Count of times each provider was invoked. Cache hits do not increment this.

Example response

json

{
  "request_id": "9c0f…",
  "account_id": "c41a…",
  "plan": "growth",
  "window": {
    "start": "2026-04-01T00:00:00.000Z",
    "end":   "2026-04-25T00:00:00.000Z",
    "granularity": "day"
  },
  "total": {
    "requests": 2412,
    "billable_units": 3104,
    "cache_hits": 842,
    "errors": 7,
    "provider_breakdown": { "openai": 1570, "anthropic": 1412, "gemini": 122 }
  },
  "series": [
    { "bucket": "2026-04-01", "requests": 78, "billable_units": 102, "cache_hits": 12, "errors": 0, "provider_breakdown": { "openai": 66, "anthropic": 36 } },
    { "bucket": "2026-04-02", "requests": 102, "billable_units": 131, "cache_hits": 21, "errors": 1, "provider_breakdown": { "openai": 81, "anthropic": 50 } }
  ],
  "monthly_quota": 7500
}

Tips

cache_hits is free from your rate-limit accounting but still counts toward requests.
Actual billed amount is recorded per call in cost_cents — see Billing for how that rolls up.
Pass granularity=total for a compact single number when you just want to know “how much have I used this month?”.

Response headers

Header	Description
X-RateLimit-Limit	Your plan's token-bucket capacity.
X-RateLimit-Remaining	Tokens remaining in the current window.
Retry-After	Seconds to wait before retrying. Only on `429`.

The unique call identifier is returned in the JSON body as request_id.

Errors

See the full Errors reference for payload shape and retry guidance.

Status	error.code	When	Recovery
400	`invalid_request`	Query params failed validation — non-ISO `start`/`end`, unknown `granularity`, or `start >= end`.	Fix the query params. Check `error.details` for the field path.
401	`unauthorized`	Missing, malformed, or revoked `Authorization: Bearer` token.	Send a valid `lvk_live_…` or `lvk_test_…` key.
500	`internal_error`	Supabase query against `usage_events` failed.	Retry with backoff. If persistent, include `request_id` in support.