Get API key balance | ToAPIs Documentation

GET

/api/v1/api-keys/{api_key_id}/balance

Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.

Behavior

Reads a given key's remaining-credit snapshot, for checking how much it can still consume. Disabled, expired, exhausted, and soft-deleted keys can all be read; keys belonging to others or that do not exist return 404.

The response is the balance snapshot persisted in the database, not a live-computed figure: an unlimited key's remaining amount is null while its used amount is normal. Live used counters for the daily/monthly limits are not read here.

Call charges are written to the database in batches, so readings taken before a batch lands can lag slightly behind actual usage.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model keys are not accepted and X-User-Id is not required. See access rules.

Request parameters

api_key_idstringpathrequired

Decimal string ID of your ordinary model key, not the sk- secret.

No body or query parameters are accepted.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/api-keys/43/balance' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://api.toapis.com/api/v1/api-keys/43/balance",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43/balance", {
  method: "GET",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictitious data. See Get API key for key metadata and Access for the shared response and error contract.

data.api_key_idstring

Key ID.

data.statusstring

Current key state, including deleted.

data.unlimitedboolean

Whether the key has unlimited quota.

data.remaining_creditsstring | null

Remaining credits; null if unlimited.

data.remaining_usdstring | null

Remaining USD equivalent; null if unlimited.

data.used_creditsstring

Cumulative used credits.

data.used_usdstring

Cumulative used USD equivalent.

data.daily_limit_creditsstring | null

Daily credit limit; null when no daily limit is configured.

data.monthly_limit_creditsstring | null

Monthly credit limit; null when no monthly limit is configured.

data.credits_per_usdstring

Credits per 1 USD.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": "43",
    "status": "enabled",
    "unlimited": false,
    "remaining_credits": "500",
    "remaining_usd": "5",
    "used_credits": "100",
    "used_usd": "1",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "credits_per_usd": "100"
  }
}