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

# Obter uso da API Key

> Retorna o detalhamento paginado de uso para uma API Key de usuário.

## Visão geral

Este endpoint retorna o detalhamento de uso por API Key sem expor metadata de roteamento físico.

## Parâmetros de query

| Parâmetro       | Tipo    | Padrões / limites                     | Descrição                                                                                          |
| --------------- | ------- | ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | padrão `1`, mínimo `1`                | Número da página começando em 1                                                                    |
| `limit`         | integer | padrão `50`, mínimo `1`, máximo `100` | Tamanho da página                                                                                  |
| `model`         | string  | comprimento máximo `100`              | Nome do modelo solicitado                                                                          |
| `modelVendor`   | string  | comprimento máximo `100`              | Fornecedor público do modelo                                                                       |
| `scene`         | enum    | -                                     | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                                     | `platform` ou `byok`                                                                               |
| `startDate`     | string  | -                                     | Limite inferior inclusivo; aceita RFC3339 com fuso horário ou `YYYY-MM-DD`                         |
| `endDate`       | string  | -                                     | Limite superior inclusivo; aceita RFC3339 com fuso horário ou `YYYY-MM-DD`                         |

Se `startDate` e `endDate` forem enviados juntos, `startDate` deve ser anterior ou igual a `endDate`.

## Observações

* A resposta é paginada.
* A resposta inclui apenas campos públicos de faturamento e reporting.
* Cada item de usage também pode incluir `billing_transaction_id` depois que a requisição subjacente atingir o estado de liquidação concluída. Use esse valor junto com `request_id` para reconciliação por requisição.
* A metadata de roteamento interno e dos canais físicos permanece oculta de forma intencional.

## Exemplo

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

## Requisição / Resposta

Consulte o painel interativo de OpenAPI acima para ver o schema exato e os campos da resposta.

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