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

# 查询余额和用量

> 使用 CometAPI CLI 或查询服务 API 获取账户余额、用量以及按 key 统计的配额详情。

CometAPI 提供两种方式来检查账户余额和用量：**CometAPI CLI** 和位于 `query.cometapi.com` 的 **query service API**。

如果您使用 Workspace，请参阅 [使用 CometAPI Workspace 管理团队](/zh-Hans/workspace/overview)，了解共享组织额度和计费角色。

***

## CometAPI CLI

通过一条命令在终端中检查你的余额。安装方式请参阅 [CometAPI CLI 概览](/zh-Hans/libraries/cli/overview)。

```bash theme={null}
cometapi balance
```

添加 `--source token` 可查看按 key 统计的详情：

```bash theme={null}
cometapi balance --source token
```

有关所有可用选项，请参阅 [命令参考](/zh-Hans/libraries/cli/commands)。

***

## 查询服务 API

`GET https://query.cometapi.com/user/quota`

返回账户级余额、累计用量、总请求次数以及每个 key 的配额详情。该端点使用位于 `query.cometapi.com` 的独立查询服务，并通过查询参数 `key` 进行身份验证，而不是使用 Bearer Token。

<Tip>
  为余额查询使用专用 API key。如果你希望限制暴露风险，请关闭 Unlimited Quota，并将信用额度设置为控制台允许的最小正数值。
</Tip>

### 请求参数

| Parameter    | Type   | Required | Description                |
| ------------ | ------ | -------- | -------------------------- |
| `key`        | string | Yes      | 你的 CometAPI API key        |
| `start_date` | string | No       | 每日明细的开始日期（`YYYY-MM-DD` 格式） |
| `end_date`   | string | No       | 每日明细的结束日期（`YYYY-MM-DD` 格式） |

当提供 `start_date` 和 `end_date` 时，响应会包含 `daily_quota` 字段，按天提供每个 key 的用量明细。

### 响应字段

| Field                               | Type    | Description                                 |
| ----------------------------------- | ------- | ------------------------------------------- |
| `username`                          | string  | 用户名                                         |
| `total_quota`                       | number  | 当前账户余额（USD）                                 |
| `total_used_quota`                  | number  | 累计用量（USD）                                   |
| `request_count`                     | integer | 总请求次数                                       |
| `keys`                              | array   | 每个 key 的配额详情                                |
| `keys[].name`                       | string  | API key 名称                                  |
| `keys[].remain_quota`               | number  | key 剩余配额；`-1` 表示无限制                         |
| `keys[].used_quota`                 | number  | key 已用配额；`-1` 表示无限制                         |
| `daily_quota`                       | object  | 每日用量明细（仅当设置了 `start_date` 和 `end_date` 时返回） |
| `daily_quota[date]`                 | array   | 该日期下每个 key 的用量条目                            |
| `daily_quota[date][].token_name`    | string  | API key 名称                                  |
| `daily_quota[date][].quota_used`    | number  | 该 key 在该日期的用量（USD）                          |
| `daily_quota[date][].request_count` | integer | 该 key 在该日期的请求次数                             |

### 代码示例

查询账户余额：

<CodeGroup>
  ```bash curl theme={null}
  curl "https://query.cometapi.com/user/quota?key=$COMETAPI_KEY"
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.get(
      "https://query.cometapi.com/user/quota",
      params={"key": os.environ["COMETAPI_KEY"]}
  )
  data = resp.json()
  print(f"Balance: ${data['total_quota']:.2f}")
  print(f"Used: ${data['total_used_quota']:.2f}")
  print(f"Requests: {data['request_count']}")
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(
    `https://query.cometapi.com/user/quota?key=${process.env.COMETAPI_KEY}`
  );
  const data = await resp.json();
  console.log(`Balance: $${data.total_quota.toFixed(2)}`);
  console.log(`Used: $${data.total_used_quota.toFixed(2)}`);
  console.log(`Requests: ${data.request_count}`);
  ```
</CodeGroup>

### 响应示例

```json theme={null}
{
  "username": "example_user",
  "total_quota": 2105.23,
  "total_used_quota": 21.07,
  "request_count": 1221,
  "keys": [
    {
      "name": "my-key",
      "remain_quota": 8.94,
      "used_quota": 2.10
    }
  ]
}
```

### 每日明细示例

查询某个日期范围内的每日用量：

```bash theme={null}
curl "https://query.cometapi.com/user/quota?key=$COMETAPI_KEY&start_date=2026-04-13&end_date=2026-04-14"
```

响应除包含相同的顶层字段外，还会包含 `daily_quota`：

```json theme={null}
{
  "username": "example_user",
  "total_quota": 2105.23,
  "total_used_quota": 21.07,
  "request_count": 1221,
  "daily_quota": {
    "2026-04-13T00:00:00Z": [
      {
        "token_name": "my-key",
        "quota_used": 4.27,
        "request_count": 59
      }
    ],
    "2026-04-14T00:00:00Z": [
      {
        "token_name": "my-key",
        "quota_used": 0.57,
        "request_count": 36
      }
    ]
  }
}
```