> ## 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 또는 query service API를 사용해 계정 잔액, 사용량, 키별 할당량 세부 정보를 조회합니다.

CometAPI는 계정 잔액과 사용량을 확인하는 두 가지 방법을 제공합니다: **CometAPI CLI**와 `query.cometapi.com`의 **query service API**입니다.

Workspace를 사용하는 경우 [CometAPI Workspace로 팀 관리](/ko/workspace/overview)에서 공유 Organization Credits와 청구 역할을 알아보세요.

***

## CometAPI CLI

터미널에서 한 번의 명령으로 잔액을 확인하세요. 설치 방법은 [CometAPI CLI 개요](/ko/libraries/cli/overview)를 참고하세요.

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

키별 세부 정보를 보려면 `--source token`을 추가하세요:

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

사용 가능한 모든 옵션은 [commands reference](/ko/libraries/cli/commands)를 참고하세요.

***

## Query service API

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

계정 수준 잔액, 누적 사용량, 총 요청 수, 키별 quota 세부 정보를 반환합니다. 이 엔드포인트는 `query.cometapi.com`의 별도 query service를 사용하며, Bearer Token 대신 `key` 쿼리 파라미터로 인증합니다.

<Tip>
  잔액 조회에는 전용 API 키를 사용하세요. 노출을 제한하려면 Unlimited Quota를 비활성화하고 대시보드에서 허용하는 가장 작은 양수 credit limit를 설정하세요.
</Tip>

### Request parameters

| Parameter    | Type   | Required | Description                      |
| ------------ | ------ | -------- | -------------------------------- |
| `key`        | string | Yes      | CometAPI API 키                   |
| `start_date` | string | No       | 일별 상세 내역의 시작 날짜(`YYYY-MM-DD` 형식) |
| `end_date`   | string | No       | 일별 상세 내역의 종료 날짜(`YYYY-MM-DD` 형식) |

`start_date`와 `end_date`가 제공되면 응답에 `daily_quota` 필드가 포함되며, 키별 사용량이 일자별로 분해되어 표시됩니다.

### Response fields

| Field                               | Type    | Description                                      |
| ----------------------------------- | ------- | ------------------------------------------------ |
| `username`                          | string  | 사용자 이름                                           |
| `total_quota`                       | number  | 현재 계정 잔액(USD)                                    |
| `total_used_quota`                  | number  | 누적 사용량(USD)                                      |
| `request_count`                     | integer | 총 요청 수                                           |
| `keys`                              | array   | 키별 quota 세부 정보                                   |
| `keys[].name`                       | string  | API 키 이름                                         |
| `keys[].remain_quota`               | number  | 키의 남은 quota, `-1`은 무제한을 의미                       |
| `keys[].used_quota`                 | number  | 키의 사용된 quota, `-1`은 무제한을 의미                      |
| `daily_quota`                       | object  | 일별 사용량 상세 내역(`start_date`와 `end_date`가 설정된 경우에만) |
| `daily_quota[date]`                 | array   | 해당 날짜의 키별 사용량 항목                                 |
| `daily_quota[date][].token_name`    | string  | API 키 이름                                         |
| `daily_quota[date][].quota_used`    | number  | 해당 날짜에 해당 키가 사용한 사용량(USD)                        |
| `daily_quota[date][].request_count` | integer | 해당 날짜에 해당 키의 요청 수                                |

### Code examples

계정 잔액 조회:

<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>

### Response example

```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
    }
  ]
}
```

### Daily breakdown example

날짜 범위의 일별 사용량 조회:

```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
      }
    ]
  }
}
```