# Query Your Balance with an API Key
> Query the remaining quota of the current key with an sk- API key: GET /v1/user/balance returns is_active / balance / unit, and GET /v1/credits returns OpenRouter-style total_credits / total_usage, compatible with third-party clients such as cc-switch.
URL: https://docs.lmuai.com/en/docs/api/balance
Use an `sk-` API key to query **the remaining quota and availability of that key**. It is intended for third-party clients that display a balance in their UI, or for scripts that monitor the balance.
**These endpoints are read-only**: they are not billed and do not consume quota. Authentication only validates the key itself, so you can still read the remaining quota even after the quota is used up and business requests would be rejected (in that case `is_active` is `false`).
***
## 1. Endpoint overview [#1-endpoint-overview]
| Endpoint | Client format it matches | Returns |
| ---------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
| `GET /v1/user/balance` | cc-switch generic balance template | `is_active` / `balance` / `unit`, plus `used` / `total` when the key has a total quota |
| `GET /user/balance` | Same as above, for a Base URL without `/v1` | Identical to the row above |
| `GET /v1/credits` | OpenRouter style | `data.total_credits` / `data.total_usage` |
| Item | Value |
| --------------- | -------------------------------- |
| Base URL | `https://api.lmuai.com` |
| Authentication | `Authorization: Bearer ` |
| Response format | JSON |
| Login required | No, the API key is enough |
`/user/balance` is an alias of `/v1/user/balance` (used when a client's Base URL is set without `/v1`). `/v1/credits` has **no** root-path alias and must include `/v1`.
***
## 2. Which balance is returned [#2-which-balance-is-returned]
`balance` is not necessarily the account wallet balance — it is **the remaining quota actually available to the current key**, resolved in this order:
| Order | Key situation | What `balance` means |
| ----- | --------------------------------------- | --------------------------------------------------------------------------------- |
| 1 | The key has its own total quota | That key's remaining quota (`total - used`) |
| 2 | The key belongs to a subscription group | The subscription's remaining quota (`unit` is `requests` when counted by request) |
| 3 | Neither of the above | The account wallet balance |
`is_active` additionally indicates whether the key **can currently be used for business calls**: it is `true` when the key is active, not expired and its total quota is not used up; it is also `false` when the key belongs to a subscription group with no active subscription.
***
## 3. `GET /v1/user/balance` [#3-get-v1userbalance]
```http
GET /v1/user/balance HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Response — wallet balance mode** (key has no quota and is not in a subscription group):
```json
{
"is_active": true,
"balance": 1575.13,
"unit": "USD"
}
```
**Response — the key has a total quota** (in this case `used` and `total` are also returned):
```json
{
"is_active": true,
"balance": 6,
"unit": "USD",
"used": 4,
"total": 10
}
```
**Response — subscription group counted by request**:
```json
{
"is_active": true,
"balance": 842,
"unit": "requests"
}
```
### Response fields [#response-fields]
| Field | Type | Description |
| ----------- | ------ | -------------------------------------------------------------------------------- |
| `is_active` | bool | Whether the key can currently be used for business calls |
| `balance` | number | Remaining quota; see `unit` for the unit |
| `unit` | string | `USD` (default), or `requests` for subscription groups counted by request |
| `used` | number | **Only present when the key has a total quota** — quota already used by this key |
| `total` | number | **Only present when the key has a total quota** — this key's total quota |
`used` / `total` only have meaningful values in key-quota mode. Wallet balance and subscription modes do not return these fields — use `balance` and do not derive it from `total - used`.
***
## 4. `GET /v1/credits` [#4-get-v1credits]
OpenRouter-style balance format; clients display the remaining quota as `total_credits - total_usage`.
```http
GET /v1/credits HTTP/1.1
Host: api.lmuai.com
Authorization: Bearer sk-xxxxxxxx
```
**Response:**
```json
{
"data": {
"total_credits": 20,
"total_usage": 4
}
}
```
| Field | Type | Description |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `data.total_credits` | number | **Used + remaining**, so that `total_credits - total_usage` equals exactly the remaining quota |
| `data.total_usage` | number | Quota already used |
`total_credits` is a composite value of "used + remaining" — it is **not** the literal quota limit. In wallet balance mode `total_usage` is `0` and `total_credits` equals the balance; when the quota is used up the remaining quota is clamped to `0`, so `total_credits` then equals the amount used.
***
## 5. Configuring third-party clients [#5-configuring-third-party-clients]
| Client / scenario | How to configure |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| cc-switch generic balance template | Base URL `https://api.lmuai.com` (without `/v1`) or `https://api.lmuai.com/v1` (with `/v1`) — both work |
| OpenRouter-compatible clients (Kelivo, RikkaHub, etc.) | Base URL `https://api.lmuai.com/v1`; the client will request `/v1/credits` |
| Your own script | Call `/v1/user/balance` directly — its fields are easier to read |
```bash
curl -s https://api.lmuai.com/v1/user/balance \
-H "Authorization: Bearer sk-xxxxxxxx"
```
***
## 6. Error responses [#6-error-responses]
Balance queries use the gateway's standard API key authentication, so errors come back in the same format as other API calls. When the request has no key:
```json
{
"code": "API_KEY_REQUIRED",
"message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}
```
| Status code | `code` | Scenario |
| ----------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | — | Normal response; an exhausted quota, an expired key or a missing subscription also returns `200`, with `is_active: false` meaning the key cannot be used |
| `401` | `API_KEY_REQUIRED` | The request has no API key |
| `401` | `INVALID_API_KEY` | The key does not exist or is malformed |
| `401` | `API_KEY_DISABLED` | The key has been disabled |
| `403` | `ACCESS_DENIED` | The key has an IP allowlist / blocklist and the current IP is not allowed |
For general errors, see [Error Codes](/en/docs/guide/errors).
***
## 7. Difference from "Export Usage Details" [#7-difference-from-export-usage-details]
| | The balance endpoints in this page | [Export Usage Details](/en/docs/api/usage-export) |
| -------------- | ------------------------------------------------------ | --------------------------------------------------- |
| Authentication | `sk-` API key | Account and password exchanged for a JWT |
| Granularity | Remaining quota of the current key | Account-level, per-request details |
| Use case | Displaying the balance in a client, balance monitoring | Billing export, reconciliation, feeding a BI system |
`GET /v1/usage` sits between the two: it also takes an `sk-` key and returns today's / cumulative usage statistics and quota information for the current key, with more detailed fields.