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

# 토큰 사용량 조회

> 보유한 모든 API Key의 요청별 Token 소비량과 비용 조회

* 보유한 **모든** API Key의 요청별 Token 소비량과 비용을 조회하거나 단일 Key로 필터링
* 입력, 출력, 캐시 히트 Token을 각각 집계
* 요약 엔드포인트로 Key별 합계 제공
* 커서 기반 페이지네이션, 기간은 최대 31일

이 엔드포인트들은 과금 로그를 읽어 과금된 각 요청의 Token 내역과 비용, 그리고 Key별 집계를 반환합니다. 단일 Key의 총 잔액만 반환하는 [토큰 잔액 조회](/docs/ko/api-reference/account/token-balance)를 보완합니다.

## 인증

<ParamField header="Authorization" type="string" required>
  이 엔드포인트는 `sk-` API Key가 아닌 **사용자 계정**으로 인증합니다.

  1. [계정 설정 페이지](https://toapis.com/dashboard/settings)를 열고 "시스템 액세스 토큰" 카드에서 **생성**을 클릭해 액세스 토큰을 발급합니다(`sk-` 키가 아님). 다시 생성하면 이전 토큰은 무효화됩니다.
  2. 액세스 토큰과 사용자 ID를 함께 전송합니다:

  ```
  Authorization: Bearer YOUR_ACCESS_TOKEN
  X-User-Id: YOUR_USER_ID
  ```

  숫자 형태의 사용자 ID는 같은 설정 페이지에 표시됩니다.
</ParamField>

<ParamField header="X-User-Id" type="string" required>
  숫자 형태의 사용자 ID. 액세스 토큰과 함께 필수입니다.
</ParamField>

## 엔드포인트

```
GET /api/usage/tokens/requests   # 요청별 상세
GET /api/usage/tokens/summary    # Key별 집계
```

## 쿼리 파라미터

두 엔드포인트 모두 동일한 파라미터를 받습니다. 정의되지 않았거나 중복된 파라미터는 `422`로 거부됩니다.

<ParamField query="start_timestamp" type="integer" required>
  기간 시작, Unix 초 타임스탬프(해당 시각 포함).
</ParamField>

<ParamField query="end_timestamp" type="integer" required>
  기간 종료, Unix 초 타임스탬프(해당 시각 미포함). `start_timestamp`보다 커야 하며 기간은 최대 31일입니다.
</ParamField>

<ParamField query="token_id" type="integer">
  선택. 숫자 토큰 ID로 단일 API Key를 지정합니다. 생략하면 모든 Key가 포함됩니다.
</ParamField>

<ParamField query="page_size" type="integer" default="50">
  페이지당 행 수, `1`–`100`.
</ParamField>

<ParamField query="cursor" type="string">
  이전 응답의 `meta.next_cursor`로 반환된 페이지네이션 커서. 생성된 것과 동일한 엔드포인트, 기간, `token_id` 필터에서만 유효합니다.
</ParamField>

## 응답

`GET /api/usage/tokens/requests`는 과금된 요청마다 한 행을 최신 순으로 반환합니다.

<ResponseField name="log_id" type="integer">
  요청에 대응하는 내부 로그 ID. 응답 내에서 고유합니다.
</ResponseField>

<ResponseField name="created_at" type="integer">
  요청이 과금된 시각, Unix 초 타임스탬프.
</ResponseField>

<ResponseField name="token_id" type="integer">
  요청을 수행한 API Key ID.
</ResponseField>

<ResponseField name="token_name" type="string">
  API Key 이름.
</ResponseField>

<ResponseField name="model_name" type="string">
  요청을 처리한 모델.
</ResponseField>

<ResponseField name="task_id" type="string">
  비동기 요청(이미지/비디오 생성)의 태스크 ID. 동기 요청에서는 비어 있습니다.
</ResponseField>

<ResponseField name="prompt_tokens" type="integer">
  과금된 입력 Token 수.
</ResponseField>

<ResponseField name="completion_tokens" type="integer">
  과금된 출력 Token 수.
</ResponseField>

<ResponseField name="cache_tokens" type="integer | null">
  캐시에서 읽은 입력 Token 수(캐시 히트). 업스트림이 보고하지 않으면 `null`입니다.
</ResponseField>

<ResponseField name="cache_creation_tokens" type="integer | null">
  캐시에 기록된 Token 수. 보고되지 않으면 `null`입니다.
</ResponseField>

<ResponseField name="reported_total_tokens" type="integer | null">
  업스트림 프로바이더가 보고한 총 Token 수(있는 경우).
</ResponseField>

<ResponseField name="total_tokens" type="integer">
  `prompt_tokens + completion_tokens`.
</ResponseField>

<ResponseField name="billing_phase" type="string">
  `pre_consumed`, `settled`, 또는 상세 과금 메타데이터 이전의 로그는 `unknown`.
</ResponseField>

<ResponseField name="quota" type="integer">
  소비된 쿼터(플랫폼 내부 단위).
</ResponseField>

<ResponseField name="cost_usd" type="string">
  미국 달러로 환산한 비용. `quota / quota_per_usd`로 계산합니다(`meta` 참조). 정밀도 유지를 위해 문자열로 반환합니다.
</ResponseField>

`GET /api/usage/tokens/summary`는 API Key별로 한 행을 `token_id` 오름차순으로 반환합니다.

<ResponseField name="token_id" type="integer">
  API Key ID.
</ResponseField>

<ResponseField name="request_count" type="integer">
  기간 내 과금 요청 수.
</ResponseField>

<ResponseField name="prompt_tokens" type="integer">
  이 Key의 입력 Token 합계.
</ResponseField>

<ResponseField name="completion_tokens" type="integer">
  이 Key의 출력 Token 합계.
</ResponseField>

<ResponseField name="total_tokens" type="integer">
  `prompt_tokens + completion_tokens`.
</ResponseField>

<ResponseField name="quota" type="integer">
  이 Key가 소비한 쿼터 합계.
</ResponseField>

<ResponseField name="cost_usd" type="string">
  이 Key의 미국 달러 비용 합계.
</ResponseField>

### Meta

<ResponseField name="meta.has_more" type="boolean">
  다음 페이지가 있는지 여부.
</ResponseField>

<ResponseField name="meta.next_cursor" type="string">
  `cursor`로 전달하면 다음 페이지를 가져옵니다. `has_more`가 `false`이면 비어 있습니다.
</ResponseField>

<ResponseField name="meta.quota_per_usd" type="string">
  `cost_usd` 환산에 사용된 미국 달러당 내부 쿼터 단위 수.
</ResponseField>

<ResponseField name="meta.consume_logging_enabled" type="boolean">
  소비 로깅 활성화 여부. `false`이면 응답이 비어 있을 수 있습니다.
</ResponseField>

<ResponseField name="meta.refunds_included" type="boolean">
  현재 항상 `false`이며 환불 금액은 차감되지 않습니다.
</ResponseField>

<RequestExample>
  ```bash cURL — 요청별 상세 theme={null}
  curl --request GET \
    --url 'https://toapis.com/api/usage/tokens/requests?start_timestamp=1759708800&end_timestamp=1760313600&page_size=100' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'X-User-Id: YOUR_USER_ID'
  ```

  ```bash cURL — 단일 Key 집계 theme={null}
  curl --request GET \
    --url 'https://toapis.com/api/usage/tokens/summary?start_timestamp=1759708800&end_timestamp=1760313600&token_id=45' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'X-User-Id: YOUR_USER_ID'
  ```

  ```python Python — 전체 페이지 순회 theme={null}
  import requests

  API_BASE = 'https://toapis.com'
  headers = {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'X-User-Id': 'YOUR_USER_ID',
  }
  params = {
      'start_timestamp': 1759708800,
      'end_timestamp': 1760313600,
      'page_size': 100,
  }

  while True:
      r = requests.get(f'{API_BASE}/api/usage/tokens/requests',
                       headers=headers, params=params)
      body = r.json()
      for row in body['data']:
          print(row['created_at'], row['token_name'], row['model_name'],
                row['prompt_tokens'], row['completion_tokens'],
                row['cache_tokens'], row['cost_usd'])
      if not body['meta']['has_more']:
          break
      params['cursor'] = body['meta']['next_cursor']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - requests theme={null}
  {
    "success": true,
    "data": [
      {
        "log_id": 10241024,
        "created_at": 1760001234,
        "token_id": 45,
        "token_name": "prod-backend",
        "model_name": "gpt-5.1",
        "task_id": "",
        "prompt_tokens": 148320,
        "completion_tokens": 2198,
        "cache_tokens": 96000,
        "cache_creation_tokens": 0,
        "reported_total_tokens": 150518,
        "total_tokens": 150518,
        "billing_phase": "settled",
        "quota": 7839,
        "cost_usd": "0.015678"
      }
    ],
    "meta": {
      "start_timestamp": 1759708800,
      "end_timestamp": 1760313600,
      "page_size": 100,
      "has_more": true,
      "next_cursor": "eyJraW5kIjoicmVxdWVzdHMiLC4uLn0",
      "cost_basis": "consume_log_quota",
      "currency": "USD",
      "quota_per_usd": "500000",
      "consume_logging_enabled": true,
      "refunds_included": false,
      "total_tokens_basis": "logged_prompt_plus_completion"
    }
  }
  ```

  ```json 200 - summary theme={null}
  {
    "success": true,
    "data": [
      {
        "token_id": 45,
        "request_count": 87,
        "prompt_tokens": 3200400,
        "completion_tokens": 150220,
        "total_tokens": 3350620,
        "quota": 401234,
        "cost_usd": "0.802468"
      }
    ],
    "meta": {
      "start_timestamp": 1759708800,
      "end_timestamp": 1760313600,
      "page_size": 50,
      "has_more": false,
      "next_cursor": "",
      "cost_basis": "consume_log_quota",
      "currency": "USD",
      "quota_per_usd": "500000",
      "consume_logging_enabled": true,
      "refunds_included": false,
      "total_tokens_basis": "logged_prompt_plus_completion"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": {
      "code": "unauthorized",
      "message": "user authentication is required"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "success": false,
    "error": {
      "code": "invalid_query",
      "message": "time range must be positive and no longer than 31 days"
    }
  }
  ```

  ```json 503 theme={null}
  {
    "success": false,
    "error": {
      "code": "query_timeout",
      "message": "usage query exceeded the time limit; use a shorter time range"
    }
  }
  ```
</ResponseExample>

## 참고 사항

* **과금된** 요청만 표시됩니다. 과금되지 않은 실패 요청은 나타나지 않으며, 요청별 성공 여부 필드도 반환되지 않습니다.
* 비용은 과금 시점에 기록된 쿼터를 기준으로 하며 현재 카탈로그 가격으로 재계산되지 않고, 환불도 차감되지 않습니다.
* 이 엔드포인트들은 원본 API Key, 채널, IP 주소, 요청/응답 내용을 노출하지 않습니다.
* `cursor`는 엔드포인트, 기간, `token_id` 필터에 바인딩되므로 다른 쿼리 간에 재사용하지 마세요.
* 쿼리는 짧은 시간 제한이 있습니다. `query_timeout`이 반환되면 기간을 줄여서 다시 시도하세요.


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