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

# Obtenir l’usage d’une API Key

> Retourne les détails d’usage paginés d’une API Key utilisateur.

## Vue d’ensemble

Cet endpoint renvoie les détails d’usage au niveau de la clé sans exposer les métadonnées de routage physique.

## Paramètres de requête

| Paramètre       | Type    | Valeurs par défaut / limites                 | Description                                                                                        |
| --------------- | ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | valeur par défaut `1`, min. `1`              | Numéro de page à partir de 1                                                                       |
| `limit`         | integer | valeur par défaut `50`, min. `1`, max. `100` | Nombre d’éléments par page                                                                         |
| `model`         | string  | longueur maximale `100`                      | Nom du modèle demandé                                                                              |
| `modelVendor`   | string  | longueur maximale `100`                      | Fournisseur public du modèle                                                                       |
| `scene`         | enum    | -                                            | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                                            | `platform` ou `byok`                                                                               |
| `startDate`     | string  | -                                            | Borne inférieure incluse ; accepte RFC3339 avec fuseau horaire ou `YYYY-MM-DD`                     |
| `endDate`       | string  | -                                            | Borne supérieure incluse ; accepte RFC3339 avec fuseau horaire ou `YYYY-MM-DD`                     |

Si `startDate` et `endDate` sont fournis ensemble, `startDate` doit être antérieur ou égal à `endDate`.

## Notes

* Les champs monétaires sont réservés au USD. Les entrées `CNY` sont obsolètes et renvoient `400 currency_retired`.

* La réponse est paginée.

* La réponse ne contient que des champs publics de billing et de reporting.

* Une ligne d’usage peut aussi inclure `billing_transaction_id` une fois que la requête sous-jacente a été réglée. Utilisez-le avec `request_id` pour le rapprochement au niveau de la requête.

* Les métadonnées de routage interne et de canaux physiques restent masquées.

## Exemple

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

## Requête / Réponse

Utilisez le panneau OpenAPI interactif ci-dessus pour obtenir le schéma exact et les champs de réponse.

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