/api/v1/account/balanceLive token balance, plan, and days until next refill.
Live token balance, plan, and days until next refill. EXEMPT — does not consume tokens. Accepts session JWT (browser dashboard) OR `X-API-Key` (server-side automation pre-flighting bursty workloads).
freeSince v3.16.0
Why use this
Live customer-facing balance probe — the canonical 'how many tokens do I have left?' call. EXEMPT (`cost: 0`) so balance polling never debits the ledger; safe to call as aggressively as 1 Hz. Returns the current balance, plan tier (free / paid), monthly quota, days until next refill, and a `suspended` boolean that flips to `true` when balance hits zero (subsequent billed calls then return HTTP 402). Customer dashboards typically poll every 30 seconds for near-real-time display; server-side automation scripts should poll before bursty workloads to pre-flight the budget and avoid mid-batch 402s. For per-endpoint spend breakdowns use `/api/v1/account/usage`; for the full debit/credit ledger use `/api/v1/account/transactions`.
Common use case
Customer dashboard polls this every 30 seconds for near-real-time balance display. Server-side scripts can also poll before bursty workloads to avoid 402s.
Live customer-facing balance probe — the "how many tokens do I have left?" call. EXEMPT (cost: 0) so balance polling never debits the ledger. Returns plan tier, monthly quota, days until next refill, and suspended flag (true when balance hits zero). Customer dashboards typically poll this every 30 seconds; server-side scripts should poll it before bursty workloads to avoid mid-batch 402s.
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| current_balance | integer | no | Tokens left in the current billing cycle. Always non-negative — when a billed call would push this below zero, the call returns 402 instead of debiting and the balance stays at the pre-call value. Refilled to `monthly_quota` on `billing_cycle_end`; balances do NOT roll over. |
| plan | string | no | Plan tier — `free` (2,000 tokens/month, no credit card required) or `paid` ($29/mo, 200,000 tokens/month). Use to gate feature visibility client-side (e.g. show 'Upgrade for full Try-It' button on free plans only). |
| plan_display_name | string | no | Human-readable plan name for UI display (e.g. `Free`, `Paid`). Casing follows brand guidelines — use this verbatim in dashboards rather than capitalizing the `plan` field client-side. |
| monthly_quota | integer | no | Total tokens granted on each billing-cycle refill. `2000` for free; `200000` for paid. Display alongside `current_balance` for the customer-facing 'X / Y tokens used' progress bar. |
| billing_cycle_end | string | no | ISO-8601 UTC timestamp of the next refill (subscription anniversary). At this exact moment the account's `current_balance` is reset to `monthly_quota` regardless of prior balance — there is NO rollover of unused tokens. For paid customers, also coincides with Stripe billing event. |
| days_until_refill | integer | no | Whole days remaining until `billing_cycle_end` (rounded down). Useful for dashboard countdown chips ('29 days until refill'). When 0, the refill is happening within the next 24 hours. |
| suspended | boolean | no | True when `current_balance == 0` AND the account has consumed all monthly tokens — subsequent billed calls return HTTP 402 with `current_balance`, `required_cost`, `next_refill_at`, `plan`, and `upgrade_url`. False otherwise (still has balance OR has been topped up via admin grant). Use to render 'Account suspended — upgrade now' banners. |
| as_of | string | no | ISO-8601 UTC timestamp the balance snapshot was generated server-side. NOT cached — always reflects the live balance at request time, since stale balance display in the dashboard would be confusing during active token consumption. |
Sample response
·
- "current_balance": 198432
- "plan": "paid"
- "plan_display_name": "Paid"
- "monthly_quota": 200000
- "billing_cycle_end": "2026-05-26T08:39:00.000Z"
- "days_until_refill": 29
- "suspended": false
- "as_of": "2026-04-26T10:14:45.000Z"
Errors
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected server-side failure. Retry with backoff; report if persistent. |
Code samples
curl "https://api.finradar.ai/api/v1/account/balance" \
-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).