Skip to content
/api/v1/account/usage

Last-N-days daily token consumption + top-10 endpoints by spend.

Last-N-days daily token consumption + top-10 endpoints by spend. EXEMPT. Same auth model as `/balance` — accepts session JWT or `X-API-Key`.

freeSince v3.16.0

Why use this

Per-day usage histogram + top-10 endpoints by spend — drives the customer dashboard usage chart and 'where my tokens went' breakdown. EXEMPT (`cost: 0`) so dashboards can poll without quota concerns. Direct query against `token_transactions` (no rollup table in v1) — ~50ms p99 at 10K txns/day per the locked-in CONTEXT.md performance budget. The `daily[]` array is sorted by `day DESC` (most recent day first) and back-fills with `tokens_consumed: 0` only for days that had at least one transaction; gap-days are absent from the array (frontend should densify if a continuous bar chart is desired). The `top_endpoints[]` array is sorted by `tokens DESC` (highest spender first) and is capped at 10 entries server-side.

Common use case

Customer dashboard renders a 30-day bar chart of daily spend + a top-10 leaderboard of which endpoints consumed the most tokens. Use to drive the 'usage trend' chip ('You burned 45,800 tokens this week, +12% vs last week').

Per-day token-spend histogram + top-10 endpoint leaderboard for the customer dashboard usage page. EXEMPT (cost: 0) so polling does not debit the account. Direct query on token_transactions (no rollup) — fast enough at our scale that the v1 strategy ships without a separate rollup table. The daily[] array densifies only days with activity (gap-days are absent — densify client-side if a continuous bar chart is needed); the top_endpoints[] array is capped at 10 server-side and sorted by spend. For live balance use GET /api/v1/account/balance; for the full signed-delta ledger use GET /api/v1/account/transactions; for self-serve subscription management use POST /api/v1/account/billing-portal.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
daysqueryoptional30—Window size in days (1-90; clamped at the bounds; non-numeric falls back to 30). 30 is the canonical dashboard default; 7 for compact widgets; 90 for quarterly review.30

Response schema

FieldTypeNullableDescription
window_daysintegernoEcho of the requested `days` query parameter, AFTER clamping to [1, 90]. Use to confirm the server applied the expected window (e.g. caller passed `days=180` but server clamped to 90 — `window_days=90` confirms the truncation).
dailyarraynoPer-day spend buckets, sorted by `day DESC` (most recent day first). Empty array on accounts with zero token activity in the window (free-tier accounts that signed up but never called a billed endpoint). Days with zero activity are ABSENT from the array — densify client-side if rendering a continuous bar chart.
daily[].daystringnoISO-8601 date (YYYY-MM-DD) at UTC day boundary. Bucketing uses `date_trunc('day', created_at)` — a debit at 23:59:00 UTC and a debit at 00:01:00 UTC the next morning land in DIFFERENT buckets. Display in user's local timezone if the dashboard expects local-day semantics.
daily[].tokens_consumedintegernoTotal tokens debited on this day (positive integer; the underlying signed delta is negative on debits, but this field flips the sign for human-readable display). Always non-negative — refunds and grants do NOT subtract from this counter (they show up in `/api/v1/account/transactions` instead). For the live signed-delta ledger use `/api/v1/account/transactions`.
daily[].callsintegernoNumber of debit transactions (= billable API calls) recorded on this day. Use to compute average cost-per-call (`tokens_consumed / calls`) for a 'most expensive day' diagnostic. Calls with `cost: 0` (auth, account, billing, etc.) are EXEMPT and never appear here.
top_endpointsarraynoTop-10 endpoints by token spend over the window, sorted by `tokens DESC`. Empty array on accounts with zero billed activity. The leaderboard is computed live (no cache) so newly added endpoints surface within seconds of their first paid call.
top_endpoints[].endpointstringnoEndpoint identifier in `METHOD /path` format (e.g. `GET /api/v1/sec/filings`, `POST /api/v1/form-13f/holdings`). Path-parameter values are normalized to placeholders so all calls to `/transactions/by-ticker/AAPL` and `/transactions/by-ticker/NVDA` aggregate into a single `/transactions/by-ticker/{ticker}` row.
top_endpoints[].tokensintegernoTotal tokens spent on this endpoint over the window (sign-flipped from the underlying signed delta — always non-negative). Use to drive the 'where did my tokens go?' donut chart on the dashboard.
top_endpoints[].callsintegernoNumber of times this endpoint was called over the window. Combined with `tokens` reveals the cost tier (`tokens / calls` ∈ {1, 5, 10, 25} for the four canonical tiers; WS connection-day rows show `tokens / calls = 100`).
as_ofstringnoISO-8601 UTC timestamp the usage snapshot was generated server-side. NOT cached — always reflects the live `token_transactions` state at request time.

Sample response

·
  • "window_days": 30
  • "daily":
    ]
  • "top_endpoints":
    ]
  • "as_of": "2026-05-02T15:51:00.000Z"
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl "https://api.finradar.ai/api/v1/account/usage" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).