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

# API 키 사용량 조회

> 사용자 API 키의 페이지네이션된 사용 내역을 반환합니다.

## 개요

이 엔드포인트는 물리 라우팅 메타데이터를 노출하지 않고 API 키 단위 사용 내역을 반환합니다.

## 쿼리 파라미터

| 파라미터            | 타입      | 기본값 / 제한                   | 설명                                                                                                 |
| --------------- | ------- | -------------------------- | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | 기본값 `1`, 최소 `1`            | 1부터 시작하는 페이지 번호                                                                                    |
| `limit`         | integer | 기본값 `50`, 최소 `1`, 최대 `100` | 페이지 크기                                                                                             |
| `model`         | string  | 최대 길이 `100`                | 요청된 모델 이름                                                                                          |
| `modelVendor`   | string  | 최대 길이 `100`                | 공개 모델 공급자                                                                                          |
| `scene`         | enum    | -                          | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                          | `platform` 또는 `byok`                                                                               |
| `startDate`     | string  | -                          | 포함되는 시작 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 지원                                                   |
| `endDate`       | string  | -                          | 포함되는 종료 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 지원                                                   |

`startDate` 와 `endDate` 를 함께 보내는 경우 `startDate` 는 `endDate` 보다 빠르거나 같아야 합니다.

## 참고 사항

* 응답은 페이지네이션됩니다.
* 응답에는 공개 가능한 과금 및 리포팅 필드만 포함됩니다.
* 기본 요청의 정산이 완료되면 각 usage 항목에 `billing_transaction_id` 가 포함될 수 있습니다. 요청 단위 정산 대조에는 `request_id` 와 함께 사용하세요.
* 내부 라우팅 및 물리 채널 메타데이터는 의도적으로 숨겨집니다.

## 예시

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video&accessChannel=platform&startDate=2026-03-01&endDate=2026-03-31" \
    -H "Authorization: Bearer mt-your-management-token"
  ```
</RequestExample>

## 요청 / 응답

정확한 스키마와 응답 필드는 상단의 인터랙티브 OpenAPI 패널을 참고하세요.

## Response example

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "api_key": {
      "id": "key_abc123def456",
      "name": "Backend Worker",
      "key_prefix": "sk-live...",
      "status": "active",
      "limit_amount": 500,
      "limit_amount_decimal": "500",
      "used_amount": 148.25,
      "used_amount_decimal": "148.25",
      "models": [
        "gpt-5-mini",
        "claude-3-7-sonnet"
      ],
      "expires_at": "2026-12-31T23:59:59.000Z",
      "last_used_at": "2026-07-08T03:12:45.000Z",
      "created_at": "2026-07-01T10:00:00.000Z"
    },
    "items": [
      {
        "request_id": "req_abc123",
        "billing_transaction_id": "billtxn_abc123",
        "model": "gpt-5-mini",
        "logical_model": "gpt-5-mini",
        "model_vendor": "OpenAI",
        "scene": "chat",
        "access_channel": "platform",
        "usage_unit": "per_token",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500",
        "prompt_tokens": 1000,
        "completion_tokens": 500,
        "total_tokens": 1500,
        "cache_read_tokens": 0,
        "cache_write_tokens": 0,
        "cache_write_tokens_5m": 0,
        "cache_write_tokens_1h": 0,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "created_at": "2026-07-08T03:15:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    },
    "summary": {
      "total_requests": 1,
      "total_cost": 0.0012,
      "total_cost_decimal": "0.0012",
      "total_prompt_tokens": 1000,
      "total_completion_tokens": 500,
      "total_tokens": 1500,
      "usage_unit_breakdown": [
        {
          "usage_unit": "per_token",
          "usage_quantity": 1500
        }
      ]
    },
    "breakdowns": {
      "by_model": [
        {
          "model": "gpt-5-mini",
          "logical_model": "gpt-5-mini",
          "model_vendor": "OpenAI",
          "requests": 1,
          "cost": 0.0012,
          "cost_decimal": "0.0012",
          "usage_quantity": 1500,
          "usage_quantity_decimal": "1500"
        }
      ],
      "by_logical_model": [
        {
          "model": "gpt-5-mini",
          "logical_model": "gpt-5-mini",
          "model_vendor": "OpenAI",
          "requests": 1,
          "cost": 0.0012,
          "cost_decimal": "0.0012",
          "usage_quantity": 1500,
          "usage_quantity_decimal": "1500"
        }
      ],
      "by_model_vendor": [
        {
          "model_vendor": "OpenAI",
          "requests": 1,
          "cost": 0.0012
        }
      ],
      "by_scene": [
        {
          "scene": "chat",
          "requests": 1,
          "cost": 0.0012,
          "cost_decimal": "0.0012"
        }
      ],
      "by_access_channel": [
        {
          "access_channel": "platform",
          "requests": 1,
          "cost": 0.0012
        }
      ],
      "daily_cost": [
        {
          "date": "2026-07-08T00:00:00.000Z",
          "cost": 0.0012,
          "cost_decimal": "0.0012"
        }
      ]
    }
  }
  ```
</ResponseExample>

## Important fields

<ResponseField name="api_key" type="object">API key summary using the same fields as list/create/update responses.</ResponseField>
<ResponseField name="items" type="array">Paginated usage rows.</ResponseField>
<ResponseField name="pagination" type="object">Pagination metadata with `page`, `limit`, `total`, and `totalPages`.</ResponseField>
<ResponseField name="summary" type="object">Aggregated totals for the selected filters.</ResponseField>
<ResponseField name="breakdowns" type="object">Aggregated breakdowns for the selected filters.</ResponseField>
<ResponseField name="items[].request_id" type="string | null">Public request identifier for support and reconciliation.</ResponseField>
<ResponseField name="items[].billing_transaction_id" type="string | null">Settled billing transaction id when available.</ResponseField>
<ResponseField name="items[].model" type="string">Requested public model name.</ResponseField>
<ResponseField name="items[].logical_model" type="string">Logical public model used for reporting.</ResponseField>
<ResponseField name="items[].model_vendor" type="string | null">Public model vendor.</ResponseField>
<ResponseField name="items[].scene" type="string | null">Public request scene.</ResponseField>
<ResponseField name="items[].access_channel" type="string">`platform` or `byok`.</ResponseField>
<ResponseField name="items[].usage_unit" type="string">Billing usage unit, such as `per_token`.</ResponseField>
<ResponseField name="items[].usage_quantity" type="number">Usage quantity as a JSON number for display.</ResponseField>
<ResponseField name="items[].usage_quantity_decimal" type="string">Exact usage quantity as a decimal string.</ResponseField>
<ResponseField name="items[].prompt_tokens" type="number">Prompt token count.</ResponseField>
<ResponseField name="items[].completion_tokens" type="number">Completion token count.</ResponseField>
<ResponseField name="items[].total_tokens" type="number">Total token count.</ResponseField>
<ResponseField name="items[].cache_read_tokens" type="number">Cache read token count.</ResponseField>
<ResponseField name="items[].cache_write_tokens" type="number">Total cache write token count.</ResponseField>
<ResponseField name="items[].cache_write_tokens_5m" type="number">Five-minute cache write token count.</ResponseField>
<ResponseField name="items[].cache_write_tokens_1h" type="number">One-hour cache write token count.</ResponseField>
<ResponseField name="items[].cost" type="number">Cost in USD as a JSON number for display.</ResponseField>
<ResponseField name="items[].cost_decimal" type="string">Exact cost in USD as a decimal string.</ResponseField>
<ResponseField name="items[].created_at" type="string">ISO usage row timestamp.</ResponseField>
<ResponseField name="summary.total_requests" type="number">Total request count.</ResponseField>
<ResponseField name="summary.total_cost" type="number">Total cost in USD as a JSON number for display.</ResponseField>
<ResponseField name="summary.total_cost_decimal" type="string">Exact total cost in USD as a decimal string.</ResponseField>
<ResponseField name="summary.total_prompt_tokens" type="number">Total prompt tokens.</ResponseField>
<ResponseField name="summary.total_completion_tokens" type="number">Total completion tokens.</ResponseField>
<ResponseField name="summary.total_tokens" type="number">Total tokens.</ResponseField>
<ResponseField name="summary.usage_unit_breakdown" type="array">Usage quantity grouped by usage unit.</ResponseField>
<ResponseField name="breakdowns.by_model" type="array">Breakdown by requested public model.</ResponseField>
<ResponseField name="breakdowns.by_logical_model" type="array">Breakdown by logical public model.</ResponseField>
<ResponseField name="breakdowns.by_model_vendor" type="array">Breakdown by public model vendor.</ResponseField>
<ResponseField name="breakdowns.by_scene" type="array">Breakdown by public request scene.</ResponseField>
<ResponseField name="breakdowns.by_access_channel" type="array">Breakdown by `platform` or `byok` access channel.</ResponseField>
<ResponseField name="breakdowns.daily_cost" type="array">Daily cost trend.</ResponseField>