Check Your Balance

Want to see how much balance you have left from a script, a program, or another tool? Call one endpoint with your API Key. You don’t need to log in to the console, and the query itself is free. You only need two things:

Item	Value
API Key	Copy it on the Tokens page in the ruoli.dev console
Endpoint	`https://ruoli.dev/api/usage/token/`

Check your balance

Replace sk-YOUR-KEY with your own Key and run:

curl https://ruoli.dev/api/usage/token/ \
  -H "Authorization: Bearer sk-YOUR-KEY"

import requests

KEY = "sk-YOUR-KEY"
resp = requests.get(
    "https://ruoli.dev/api/usage/token/",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=15,
)
data = resp.json()["data"]

# Use the account balance when user_quota is present, otherwise the token balance
quota = data.get("user_quota", data)["total_available"]
print(f"Remaining: ¥{quota / 500000:.2f}")

// Node.js 18 or later
const KEY = "sk-YOUR-KEY";

const resp = await fetch("https://ruoli.dev/api/usage/token/", {
  headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await resp.json();

// Use the account balance when user_quota is present, otherwise the token balance
const quota = (data.user_quota ?? data).total_available;
console.log(`Remaining: ¥${(quota / 500000).toFixed(2)}`);

Keep the trailing /. The full URL is https://ruoli.dev/api/usage/token/.

Read the response

Example response (the numbers are illustrative):

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "my-token",
    "total_granted": 10000000,
    "total_used": 2500000,
    "total_available": 7500000,
    "unlimited_quota": false,
    "model_limits": {},
    "model_limits_enabled": false,
    "expires_at": 0,
    "user_quota": {
      "total_available": 42000000,
      "total_used": 18000000
    }
  }
}

Field	Meaning
`total_available`	Quota this token can still use
`total_used`	Quota this token has used
`total_granted`	Total quota of this token (remaining + used)
`unlimited_quota`	`true` means the token has no limit of its own and spends the account balance
`expires_at`	Expiry time as a Unix timestamp in seconds. `0` means it never expires
`user_quota`	Balance and usage of the whole account. Only present when the token has Allow querying user quota turned on

Divide any quota number by 500000 to get the amount in CNY:

Remaining (¥) = total_available ÷ 500000
Example: 7500000 ÷ 500000 = ¥15.00

Balance for unlimited tokens

For an unlimited token, the remaining quota is negative.An unlimited token has no limit of its own. Every call is charged to your account balance, so total_available is just “0 minus usage” and doesn’t show your real balance.

To see your real account balance, give the token one extra permission:

Open the token settings

Turn on Allow querying user quota

Turn on Allow querying user quota and save.

Query again

Run the command above again and read data.user_quota.total_available. Divide it by 500000 to get your account balance.

This switch only controls whether the query endpoint can see your account balance. It doesn’t change the token’s quota or what it can call.

Show your balance in third-party clients

Many chat clients and balance checkers use OpenAI’s legacy billing endpoints. Set the API URL in the client to https://ruoli.dev and the Key to your token, and the balance usually shows up with no extra setup. These are the two endpoints they call. You can query them yourself too:

# Total quota (CNY)
curl https://ruoli.dev/v1/dashboard/billing/subscription \
  -H "Authorization: Bearer sk-YOUR-KEY"

# Used (CNY cents)
curl https://ruoli.dev/v1/dashboard/billing/usage \
  -H "Authorization: Bearer sk-YOUR-KEY"

Endpoint · field	Meaning
subscription · `hard_limit_usd`	Total token quota, already in CNY (the `usd` in the name is kept from OpenAI’s format). Unlimited tokens always show `100000000`
usage · `total_usage`	Amount the token has used, in CNY cents

Remaining (¥) = hard_limit_usd − total_usage ÷ 100

These two endpoints only count the token itself. For an unlimited token, use /api/usage/token/ above and turn on Allow querying user quota.

Common errors

401 Invalid token

The Key was copied incorrectly, or it has been deleted, disabled, or has expired. Check its status on the Tokens page and copy the full string starting with sk- again.

The token has an IP allowlist

Balance queries must also come from an allowed IP, or they are rejected.

I get a web page or a 301 redirect

Check the URL: use https and keep the trailing /. The full URL is https://ruoli.dev/api/usage/token/.

Can I poll it from a program?

Yes, but the endpoint is rate limited. Once every few minutes is enough.

Quick Start

Platform

Terms of Service

Check Your Balance