> ## 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 來取得帳戶餘額、用量與各金鑰配額詳細資訊。

CometAPI 提供兩種方式來檢查帳戶餘額與用量：**CometAPI CLI** 與位於 `query.cometapi.com` 的 **查詢服務 API**。

如果您使用 Workspace，請參閱 [使用 CometAPI Workspace 管理團隊](/zh-Hant/workspace/overview)，瞭解共用組織點數和帳務角色。

***

## CometAPI CLI

只要一個指令，就能從終端機檢查您的餘額。安裝方式請參閱 [CometAPI CLI 概覽](/zh-Hant/libraries/cli/overview)。

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

加入 `--source token` 可查看各金鑰的詳細資訊：

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

所有可用選項請參閱[指令參考](/zh-Hant/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
      }
    ]
  }
}
```