Skip to content
/api/v1/account/balance

Live token balance, token plan, billing period and subscription presence.

Live token balance, token plan, billing period and subscription presence. A Paid token grant does not itself create a subscription. 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

Canonical current token balance and plan allowance. Account management is exempt from token charges. The has_subscription flag reports whether the existing account record owns a Stripe subscription; it is independent of the free/paid token tier. Use false to offer subscription checkout and true to manage the existing subscription. A complimentary Paid grant does not imply a recurring charge or refill. The recorded billing-period end and legacy days_until_refill field are period metadata, not proof that a payment will succeed. Customer dashboards poll every 30 seconds; usage and transaction detail remain on the existing account endpoints.

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 account balance from the token ledger, with token-plan allowance, recorded billing period, suspension flag and subscription presence from the existing checkout/cancellation-owned account record. This response does not create a subscription, charge a card or alter renewal rules. A Paid token grant may have has_subscription=false. Subscription presence does not certify invoice payment; use the billing portal to manage an existing subscription.

Response schema

FieldTypeNullableDescription
has_subscriptionbooleannoWhether the existing account record contains a Stripe subscription identifier. Set by completed subscription checkout and cleared by subscription cancellation. True does not mean the latest invoice is paid: manage the existing subscription in the billing portal. False permits starting a subscription, including for complimentary Paid token accounts. No Stripe identifier is exposed.
current_balanceintegernoCurrent available token balance from the token ledger.
planstringnoToken access tier, normally free or paid. A paid token grant is independent of subscription ownership; use has_subscription for the subscription action.
plan_display_namestringnoDisplay name of the token plan.
monthly_quotaintegernoConfigured token-plan allowance. This is not proof of a paid subscription or a promised refill for a complimentary grant.
billing_cycle_endstringyesRecorded token billing-period end, if present. Actual Paid renewal depends on the existing subscription payment flow.
days_until_refillintegeryesLegacy field name: whole days until the recorded period end, clamped to zero. Not a guarantee of a complimentary Paid refill.
suspendedbooleannoCurrent suspension flag from the token ledger.
as_ofstringnoUTC time at which this balance snapshot was generated.

Sample response

·
  • "has_subscription": true
  • "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

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/balance" \
  -H "X-API-Key: YOUR_API_KEY"

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

Try it

Related endpoints

/api/v1/account/usagefree/api/v1/account/transactionsfree/api/v1/account/billing-portalfree/api/v1/billing/historyfree