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

# Balance Query

> Query the balance and usage of an account or API key

## Endpoint details

| Item | Details |
| - | - |
| Base URL | `https://maas.gravitex.ai/prod-api` |
| Data format | `application/json` |
| Character encoding | `UTF-8` |
| Protocol | `HTTPS` (required) |
| Currency | `USD` (US dollars) |

This endpoint takes no request parameters. Send the authorization header with each request.

## 1. Authentication

Send a Bearer credential in the HTTP header. **Use either of the following credentials.**

| Credential | Where to find it | Query scope |
| - | - | - |
| System access token | Console → Personal Settings → System Access Token | Entire account |
| API key | Console → Token Management. Keys usually start with `sk-`. | This key only |

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | Use `Bearer <credential>` with either credential above. |

```http theme={null}
# Option 1. System access token
Authorization: Bearer <access_token>

# Option 2. API key
Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx
```

Authentication fails if the credential is missing, invalid, deleted, or disabled, or if the account is disabled.

***

## 2. Common response structure

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": { }
}
```

| Field | Type | Description |
| - | - | - |
| `code` | integer | Application status code. `200` indicates success. |
| `msg` | string | Status message |
| `data` | object | Response data. Returns `null` on failure. |

### Application status codes

| Code | Description |
| - | - |
| 200 | Success |
| 401 | Authentication failed (missing, invalid, or disabled credential) |

> Check `code` in the response body to determine whether the request succeeded.

### Amount format

* All amounts are in **US dollars (USD)** and are returned as **strings** to avoid loss of floating-point precision.
* Balance amounts always have **four decimal places**, for example `"986.9275"`.
* Model unit prices have no zero padding, for example `"40"`, `"2.5"`, and `"0.00075"`.

***

## 3. Balance query

```
GET /api/account/balance
```

The response structure depends on the credential. Use `data.type` to identify it.

### 3.1 Account balance with a system access token (`type = account`)

| Field | Type | Description |
| - | - | - |
| `type` | string | Always `account` |
| `username` | string | Account username |
| `group` | string | Account group |
| `currency` | string | Always `USD` |
| `balance` | string | Remaining balance |
| `usedAmount` | string | Amount used |
| `totalAmount` | string | Total amount (remaining plus used) |

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "type": "account",
    "username": "demo_user",
    "group": "default",
    "currency": "USD",
    "balance": "986.9275",
    "usedAmount": "213.0725",
    "totalAmount": "1200.0000"
  }
}
```

> An enterprise sub-account can retrieve only its own balance.

### 3.2 Key quota with an API key (`type = token`)

| Field | Type | Description |
| - | - | - |
| `type` | string | Always `token` |
| `tokenName` | string | Key name |
| `group` | string | Key group. An empty value means the key inherits the account group. |
| `unlimited` | boolean | Whether the key has unlimited quota |
| `currency` | string | Always `USD` |
| `balance` | string | Remaining amount available to the key |
| `usedAmount` | string | Amount used by the key |
| `totalAmount` | string | Total key quota (remaining plus used) |
| `expiresAt` | integer | Expiration timestamp in seconds. `0` indicates no expiration. |
| `modelLimitsEnabled` | boolean | Whether model restrictions are enabled |
| `modelLimits` | string\[] | Models the key can call. An empty array is returned when restrictions are disabled. |

```json theme={null}
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "type": "token",
    "tokenName": "my-key",
    "group": "",
    "unlimited": false,
    "currency": "USD",
    "balance": "100.0000",
    "usedAmount": "50.0000",
    "totalAmount": "150.0000",
    "expiresAt": 0,
    "modelLimitsEnabled": false,
    "modelLimits": []
  }
}
```

> A key with `unlimited = true` has no key-level quota, so `balance` can be negative. Use `usedAmount` to track key usage and the account balance to determine available funds.

***

## 4. Request examples

```bash theme={null}
# Query the account balance with a system access token
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
  -H "Authorization: Bearer <access_token>"

# Query the quota for an API key
curl -s "https://maas.gravitex.ai/prod-api/api/account/balance" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx"
```

***

## 5. Notes

1. **Refresh interval.** Balance data refreshes within about one minute. Top-ups and charges may take a short time to appear.
2. **Final charges.** Use the endpoint for queries and estimates. Refer to your bill for final charges.
3. **Credential security.** Keep system access tokens private because they provide access to account-wide information. To query one key's quota, use that API key.


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