Query User Balance

Query the remaining and used quota of the current user account

GET /v1/user/balance

cURL

curl --request GET \
  --url 'https://toapis.com/v1/user/balance' \
  --header 'Authorization: Bearer <token>'

200 - Success

{
  "success": true,
  "remain_balance": 100.0,
  "used_balance": 25.5,
  "remain_credits": 20000,
  "used_credits": 5100,
  "credits_per_usd": 200,
  "unlimited_quota": false
}

• Query the overall balance of the current user account
• Monitor user-level usage
• CORS cross-origin support
• Real-time balance monitoring

Get the remaining and used balance of the current user account. This endpoint returns user-level balance information, independent of specific tokens, for viewing the overall account balance. Credit fields are also returned using the fixed conversion rate 1 USD = 200 credits.

Authorizations

Authorization · string · required

All endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer YOUR_API_KEY

Endpoints

GET /v1/user/balance
GET /user/balance

Both endpoints have the same functionality, you can use either one.

cURL

curl --request GET \
  --url 'https://toapis.com/v1/user/balance' \
  --header 'Authorization: Bearer <token>'

200 - Success

{
  "success": true,
  "remain_balance": 100.0,
  "used_balance": 25.5,
  "remain_credits": 20000,
  "used_credits": 5100,
  "credits_per_usd": 200,
  "unlimited_quota": false
}

Response

success · boolean

Whether the request was successful

message · string

Error message (only returned on failure)

remain_balance · float

User remaining balance (returned on success). Returns -1 when unlimited_quota is true

used_balance · float

User used balance (returned on success)

remain_credits · float

User remaining credits (returned on success). Credits are calculated with 1 USD = 200 credits

used_credits · float

User used credits (returned on success)

credits_per_usd · float

Credit conversion rate. Currently returns 200

unlimited_quota · boolean

Whether the user has unlimited quota. true means unlimited, false means limited

Token Balance vs User Balance

Comparison	Token Balance (/v1/balance)	User Balance (/v1/user/balance)
Scope	Single token	Entire user account
Data Source	Token’s RemainQuota and UsedQuota	User’s quota and used_quota
Use Case	Monitor single API Key usage	View overall account balance
Limited By	Token-level quota limits	User-level quota limits

Use Cases

• View overall user account balance
• Set up recharge reminders and balance alerts
• Display account balance in user dashboard

Balance Unit Information

The unit of the balance value depends on system configuration:

• USD - US Dollars
• CNY - Chinese Yuan
• Tokens - Token count

For stable integration, prefer remain_credits and used_credits when you need credit values. These fields always use 1 USD = 200 credits and do not depend on the balance display configuration.

Unlimited Quota User

When a user is set to unlimited quota:

• unlimited_quota field returns true
• remain_balance field returns -1
• The user has no quota restrictions and can use the API without limits

Common Errors

Error Message	Cause	Solution
No Authorization header	Authorization header not provided	Add Authorization: Bearer sk-xxxxx header
Failed to get user quota	User doesn’t exist	Check if the user associated with the token exists
Failed to get used quota	Database query error	Contact admin to check system status

Security Note

Your API Key is like a password. Keep it secure and don’t share it with others. Always use HTTPS in production.