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

# Lấy mức sử dụng API key

> Trả về chi tiết mức sử dụng có phân trang cho một API key người dùng.

## Tổng quan

Endpoint này trả về chi tiết mức sử dụng theo API key mà không làm lộ chi tiết thực thi của provider.

## Tham số query

| Tham số         | Kiểu    | Mặc định / giới hạn                        | Mô tả                                                                                              |
| --------------- | ------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | mặc định `1`, tối thiểu `1`                | Số trang bắt đầu từ 1                                                                              |
| `limit`         | integer | mặc định `50`, tối thiểu `1`, tối đa `100` | Kích thước mỗi trang                                                                               |
| `model`         | string  | độ dài tối đa `100`                        | Tên model được yêu cầu                                                                             |
| `modelVendor`   | string  | độ dài tối đa `100`                        | Nhà cung cấp model công khai                                                                       |
| `scene`         | enum    | -                                          | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                                          | `platform` hoặc `byok`                                                                             |
| `startDate`     | string  | -                                          | Cận dưới bao gồm; chấp nhận RFC3339 có múi giờ hoặc `YYYY-MM-DD`                                   |
| `endDate`       | string  | -                                          | Cận trên bao gồm; chấp nhận RFC3339 có múi giờ hoặc `YYYY-MM-DD`                                   |

Nếu truyền đồng thời `startDate` và `endDate`, thì `startDate` phải nhỏ hơn hoặc bằng `endDate`.

## Lưu ý

* Phản hồi có phân trang.
* Phản hồi chỉ bao gồm các trường chi phí và báo cáo công khai.
* Mỗi dòng usage cũng có thể bao gồm `billing_transaction_id` sau khi request gốc đã được settlement xong. Hãy dùng giá trị này cùng với `request_id` để đối soát ở cấp request.
* Metadata routing nội bộ và kênh vật lý sẽ tiếp tục bị ẩn.

## Ví dụ

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

## Yêu cầu / Phản hồi

Hãy dùng bảng OpenAPI tương tác phía trên để xem schema chính xác và các trường phản hồi.

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