> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruoli.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Check Your Balance

> Check your remaining quota with one API call, no console login needed

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](https://ruoli.dev) console |
| Endpoint | `https://ruoli.dev/api/usage/token/` |

## Check your balance

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

```bash curl theme={null}
curl https://ruoli.dev/api/usage/token/ \
  -H "Authorization: Bearer sk-YOUR-KEY"
```

```python Python theme={null}
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}")
```

```javascript JavaScript theme={null}
// 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)}`);
```

> [!WARNING]
>
> Keep the trailing `/`. The full URL is `https://ruoli.dev/api/usage/token/`.

## Read the response

Example response (the numbers are illustrative):

```json theme={null}
{
  "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

> [!WARNING]
>
> **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:

**1. Open the token settings**

Log in to [ruoli.dev](https://ruoli.dev), go to the **Tokens** page, and edit the token you query with.

**2. Turn on Allow querying user quota**

Turn on **Allow querying user quota** and save.

**3. Query again**

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

> [!NOTE]
>
> 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:

```bash theme={null}
# 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
```

> [!NOTE]
>
> 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

> [accordion] 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.

> [accordion] The token has an IP allowlist
>
> Balance queries must also come from an allowed IP, or they are rejected.

> [accordion] 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/`.

> [accordion] Can I poll it from a program?
>
> Yes, but the endpoint is rate limited. Once every few minutes is enough.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.