Usage

Base: /v1/usage · Auth: API key or Clerk session

GET /v1/usage

Query: window_seconds (default 86400, i.e. trailing 24h — this only affects total/succeeded/failed below, not the monthly quota fields).

{
  "total": 42,
  "succeeded": 40,
  "failed": 2,
  "period_start": "2026-09-14T10:15:00Z",
  "period_end": "2026-09-15T10:15:00Z",
  "plan": "free_user",
  "monthly_limit": 100,
  "monthly_used": 37,
  "monthly_remaining": 63,
  "monthly_period_start": "2026-09-03T08:30:00Z",
  "monthly_resets_at": "2026-10-03T08:30:00Z"
}

Field	Type	Notes
total / succeeded / failed	integer	Requests within window_seconds. Independent of the quota.
period_start / period_end	datetime	Bounds of that window_seconds window.
plan	free_user | developer_user | pro_user	The account’s current plan.
monthly_limit	integer	Renders allowed per quota cycle on this plan.
monthly_used	integer	Renders counted since monthly_period_start.
monthly_remaining	integer	monthly_limit − monthly_used.
monthly_period_start	datetime	Start of the current quota cycle.
monthly_resets_at	datetime | null	When monthly_used next goes back to 0. Set for any authenticated account in practice; treat null as unknown.

All datetimes are ISO 8601, UTC. For how the cycle is anchored, see Rate Limits & Quotas.

total/succeeded/failed count only the API key used, or the whole account when authenticated with a session. The monthly_* fields always cover the whole account: the plan quota is per account, so every key draws from the same monthly pool.