Query Balance
Query the authenticated key's spending limit, usage, and account wallet balance details.
GET /v1/balance
Returns the effective spendable balance for the authenticated API key, the key's own spending limit and usage, and the underlying account wallet balance breakdown. Authentication is required.
curl "https://api.modelrover.ai/v1/balance" \
-H "Authorization: Bearer $API_KEY"Response
Every credit amount is returned in two representations:
- A decimal credit string with up to 6 fractional digits and trailing zeros trimmed (for example,
"37.655"). - An exact
*_microinteger string (1 credit = 1,000,000 micro, for example,"37655000").
{
"object": "balance",
"available": "37.655",
"available_micro": "37655000",
"key": {
"limit": "50",
"limit_micro": "50000000",
"usage": "12.345",
"usage_micro": "12345000",
"limit_remaining": "37.655",
"limit_remaining_micro": "37655000",
"rpm_limit": 60,
"tpm_limit": 100000,
"concurrency_limit": 10,
"expires_at": 1798761600000
},
"wallet": {
"status": "active",
"available": "108.5",
"available_micro": "108500000",
"total_available": "158.5",
"total_available_micro": "158500000",
"balance": "100",
"balance_micro": "100000000",
"gift_balance": "10",
"gift_balance_micro": "10000000",
"frozen": "1.5",
"frozen_micro": "1500000",
"credit_limit": "50",
"credit_limit_micro": "50000000",
"credit_used": "0",
"credit_used_micro": "0",
"credit_remaining": "50",
"credit_remaining_micro": "50000000"
}
}Top-level fields
| Field | Type | Description |
|---|---|---|
object | string | Always balance. |
available | string | Effective spendable credits for the current key: min(key.limit_remaining, wallet.total_available) when a key limit is configured, or wallet.total_available when unlimited ("0" if the wallet is disabled). |
available_micro | string | Effective spendable amount in micro units. |
key | object | Spending cap, cumulative usage, and expiration for the authenticated API key. |
wallet | object | Real-time balance breakdown of the account wallet that owns the key. |
key fields
| Field | Type | Description |
|---|---|---|
key.limit | string | null | Configured spending limit for this key, or null if unlimited. |
key.limit_micro | string | null | Configured spending limit in micro units, or null if unlimited. |
key.usage | string | Cumulative settled usage attributed to this key. |
key.usage_micro | string | Cumulative settled usage in micro units. |
key.limit_remaining | string | null | Remaining quota under this key's spending limit (max(limit - usage, 0)), or null if unlimited. |
key.limit_remaining_micro | string | null | Remaining key quota in micro units, or null if unlimited. |
key.rpm_limit | integer | null | Configured requests-per-minute limit for this key, or null if not set on the key. |
key.tpm_limit | integer | null | Configured tokens-per-minute limit for this key, or null if not set on the key. |
key.concurrency_limit | integer | null | Configured in-flight concurrency limit for this key, or null if not set on the key. |
key.expires_at | integer | null | Expiration timestamp in Unix milliseconds, or null if the key does not expire. |
wallet fields
| Field | Type | Description |
|---|---|---|
wallet.status | string | Wallet status (active or disabled). |
wallet.available | string | Available credits excluding credit line (max(balance + gift_balance - frozen, 0)). |
wallet.available_micro | string | Available credits excluding credit line in micro units. |
wallet.total_available | string | Total spendable credits including remaining credit line (max(balance + gift_balance + credit_remaining - frozen, 0)). |
wallet.total_available_micro | string | Total spendable credits in micro units. |
wallet.balance | string | Standard top-up balance (0 when the wallet is currently using credit). |
wallet.balance_micro | string | Standard balance in micro units. |
wallet.gift_balance | string | Promotional gift balance (consumed before standard balance). |
wallet.gift_balance_micro | string | Gift balance in micro units. |
wallet.frozen | string | Credits temporarily reserved by in-flight requests. |
wallet.frozen_micro | string | Frozen credits in micro units. |
wallet.credit_limit | string | Approved credit line for the wallet. |
wallet.credit_limit_micro | string | Approved credit line in micro units. |
wallet.credit_used | string | Portion of the credit line currently used. |
wallet.credit_used_micro | string | Used credit line in micro units. |
wallet.credit_remaining | string | Remaining credit line (max(credit_limit - credit_used, 0)). |
wallet.credit_remaining_micro | string | Remaining credit line in micro units. |
Inspecting exhausted keys
Keys that are disabled or expired return 401. However, an active key that
has reached its spending cap (usage >= limit) can still call GET /v1/balance
and receives 200 with key.limit_remaining: "0" and available: "0".
Help us improve this page
Found something unclear, outdated, or incorrect?
Last updated on