Skip to content
/api/v1/billing/quota

Purchase additional REQUEST quota by debiting the USD `credit_balance` wallet at 100 requests per $1.

Purchase additional REQUEST quota by debiting the USD `credit_balance` wallet at 100 requests per $1. EXEMPT (`cost: 0`). Logs a SPEND `Transaction`. Returns 400 with `INSUFFICIENT_BALANCE` when the wallet does not cover the requested amount.

freeSince v1.0.0

Why use this

Customer-initiated request-quota top-up — debits the USD `credit_balance` wallet (in DOLLARS), adds REQUESTS (NOT tokens) to `user_plans.total_limit_api` at the fixed exchange rate of 100 requests per $1. EXEMPT (`cost: 0`). Atomic single-transaction: balance debit + quota credit + SPEND `Transaction` row are committed together. Returns 400 with `INSUFFICIENT_BALANCE` if `credit_balance < amount_dollars`. NB: this affects the LEGACY per-request meter (see [GET /api/v1/billing/subscription](/docs/account/billing-and-subscription/get-billing-subscription)) — NOT the canonical Phase 56 token meter (which has its own monthly-cycle refill and does NOT support manual top-up). To top up the USD wallet first, use [POST /api/v1/payments/create-intent](/docs/account/payments-module/post-payments-create-intent).

Common use case

Dashboard 'Buy more requests' modal: user enters $10 → POST here with `amount_dollars: 10` → backend debits wallet by $10, adds 1,000 requests to `total_limit_api`, returns success → UI updates the request-quota progress bar.

Customer-initiated request-quota top-up. EXEMPT (cost: 0). Debits the USD credit_balance wallet (in DOLLARS) and adds REQUESTS to user_plans.total_limit_api at the fixed exchange rate of 100 requests per $1. Atomic — wallet debit + quota credit + SPEND Transaction row commit together (no half-state on partial failure). Returns 400 with INSUFFICIENT_BALANCE when credit_balance < amount_dollars; gate the UI button by checking GET /api/v1/user/ credit_balance first. To fill the wallet before calling this, use POST /api/v1/payments/create-intent (one-time top-up via Stripe). Note this is the LEGACY per-request meter — NOT the canonical Phase 56 token meter (GET /api/v1/account/balance). The token meter has its own monthly-cycle refill model and does NOT currently support customer-initiated top-up; on a paid plan it refills to 200,000 tokens at the subscription anniversary.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
amount_dollarsbodyrequired——USD amount to spend (NOT cents). Positive number; integer or float (e.g. 10, 20, 12.50). Validated server-side: rejected with 400 `BAD_REQUEST` on missing/non-numeric/zero/negative; rejected with 400 `INSUFFICIENT_BALANCE` if `users.credit_balance < amount_dollars`. Each $1 buys 100 REQUESTS.10

Response schema

FieldTypeNullableDescription
statusstringnoApiResponse envelope status — `success` on 200, `error` on 4xx/5xx.
request_idstringyesPer-request correlation ID.
timestampstringnoISO-8601 UTC timestamp.
dataobjectnoPost-purchase result payload.
data.messagestringnoHuman-readable confirmation (e.g. `Successfully purchased 1000 additional API requests.`). Use for the UI success toast.
data.new_total_limitintegernoPost-purchase value of `user_plans.total_limit_api` (in REQUESTS, not tokens). Mirrors the legacy per-request quota; the new bonus quota is added on top of the plan's base allocation. Use to update the 'Total requests' progress-bar denominator client-side without a separate /api/v1/billing/subscription call.
data.new_balancenumbernoPost-purchase USD wallet balance (`users.credit_balance`). NOT in cents — server returns `float(credit_balance)`. Use to update the 'Wallet balance' chip client-side.

Sample response

·
  • "status": "success"
  • "request_id": "req_3OqK2jK9L8pQ4xZ5"
  • "timestamp": "2026-05-02T15:51:00.000Z"
  • "data":
    • "message": "Successfully purchased 1000 additional API requests."
    • "new_total_limit": 1100
    • "new_balance": 2.5
    }
}

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 -X POST "https://api.finradar.ai/api/v1/billing/quota" \
  -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).