Skip to main content
GET
Query User Balance

Query User Balance

Query the current credit balance of your user account in real-time.

Use Cases

Dashboard Display

Show real-time account balance in your application dashboard

Balance Alerts

Set up notifications when credits fall below a threshold

Recharge Reminders

Prompt users to top up credits before running out

Usage Tracking

Monitor credit consumption and track spending patterns

Important Notes

Real-time Balance: The balance returned reflects your current credit amount at the time of the request.
Rate Limiting: Avoid excessive polling. Cache the balance and refresh only when necessary (e.g., after completing a generation task).

Authorizations

Authorization
string
header
required

All API endpoints require Bearer Token authentication.

Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.

Add it to the request header:

Response

Balance retrieved successfully

code
enum<integer>
required

Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.

  • 200: Success
  • 400: Invalid request parameters
  • 401: Missing or invalid API key
  • 402: Insufficient credits
  • 403: Permission denied
  • 404: Resource not found
  • 408: Request timeout
  • 429: Rate limit exceeded
  • 500: Internal server error
  • 502: Upstream service error
  • 503: Service unavailable

See Error Codes for details.

Available options:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
Example:

200

data
object
required