Skip to content
/api/v1/billing/subscription

Get the authenticated user's subscription info and request-based API usage.

Get the authenticated user's subscription info and request-based API usage. EXEMPT (`cost: 0`). Returns plan name, request-based usage vs limit, subscription status, renewal date.

freeSince v1.0.0

Why use this

Authenticated subscription-state probe. EXEMPT (`cost: 0`). Returns the legacy request-based quota model (`reach_limit_api` / `total_limit_api`, in REQUESTS not tokens) plus plan name and Stripe subscription status. NOTE the unit distinction: this is the LEGACY per-request quota model used pre-Phase-56; the canonical token-based model is at [GET /api/v1/account/balance](/docs/account/token-pricing/get-account-balance) (in TOKENS, with cost-tier weighting). Both meters run side-by-side: a billed call decrements both `reach_limit_api` (+1 request) and the token ledger (-N tokens depending on cost tier). For plan upgrades use [POST /api/v1/payment/create-checkout-session](/docs/account/billing-and-subscription/post-payment-create-checkout-session); to buy additional request quota with the USD wallet use [POST /api/v1/billing/quota](/docs/account/billing-and-subscription/post-billing-quota).

Common use case

Dashboard 'Subscription' card: render plan name + a request-quota progress bar (`reach_limit_api / total_limit_api`) + renewal-date chip. For the token-quota progress bar (the canonical Phase 56+ surface), use /api/v1/account/balance instead.

Authenticated subscription-state surface — plan tier, request-based usage (reach_limit_api / total_limit_api), Stripe status, renewal date. EXEMPT (cost: 0). NB: this is the LEGACY per-request quota model. The canonical Phase 56+ surface is the token meter at GET /api/v1/account/balance — both meters run side-by-side and a billed call increments BOTH (request counter +1, token ledger -N). Free-tier current_period_end is null; paid accounts mirror Stripe's current_period_end. To upgrade a plan use POST /api/v1/payment/create-checkout-session; to buy additional request quota with the USD wallet use POST /api/v1/billing/quota; for the live token balance use GET /api/v1/account/balance; for the per-charge wallet ledger use GET /api/v1/billing/history.

Response schema

FieldTypeNullableDescription
statusstringnoApiResponse envelope status — `success` on 200, `error` on 4xx/5xx.
request_idstringyesPer-request correlation ID.
timestampstringnoISO-8601 UTC timestamp.
dataobjectnoSubscription state payload.
data.reach_limit_apiintegernoNumber of REQUESTS (NOT tokens) consumed by the user this billing cycle. Increments by 1 on every billed call regardless of cost tier — distinct from the token ledger which weights by cost tier (1/5/10/25). On accounts with no `user_plan` row (legacy), defaults to 0.
data.total_limit_apiintegernoTotal REQUESTS allowed this billing cycle (e.g. 100 for free, higher for paid plans). Increased by [POST /api/v1/billing/quota](/docs/account/billing-and-subscription/post-billing-quota) when the user buys additional quota with their USD `credit_balance` wallet at 100 requests per $1. NOT in tokens — this is the legacy per-request meter.
data.plan_namestringnoPlan tier — `free` (default for new signups), `weekly`, `monthly`, `pro`, `yearly`. Drives UI tier badges. Set on Stripe `checkout.session.completed` via `_handle_checkout_completed` after a successful upgrade.
data.statusstringnoStripe subscription status — `active` (paying), `past_due` (failed payment, in 7-day grace), `canceled`, `trialing`, `unpaid`. For free-tier accounts always `active`. Use to dispatch UI banners ('Update payment method' on `past_due`).
data.current_period_endstringyesISO-8601 UTC timestamp the current billing period ends (= next renewal). Null for free-tier accounts (no renewal cycle). For paid accounts coincides with the Stripe subscription's `current_period_end`.

Sample response

·
  • "status": "success"
  • "request_id": "req_3OqK2jK9L8pQ4xZ3"
  • "timestamp": "2026-05-02T15:51:00.000Z"
  • "data":
    • "reach_limit_api": 12
    • "total_limit_api": 100
    • "plan_name": "free"
    • "status": "active"
    • "current_period_end": null
    }
}

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/billing/subscription" \
  -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).