> ## 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-Key-Nutzung abrufen

> Gibt paginierte Nutzungsdetails für einen Benutzer-API-Key zurück.

## Überblick

Dieser Endpunkt gibt Nutzungsdetails auf API-Key-Ebene zurück, ohne physische Routing-Metadaten offenzulegen.

## Query-Parameter

| Parameter       | Typ     | Standard / Grenzen                  | Beschreibung                                                                                       |
| --------------- | ------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- |
| `page`          | integer | Standard `1`, min. `1`              | Seitennummer ab 1                                                                                  |
| `limit`         | integer | Standard `50`, min. `1`, max. `100` | Anzahl Einträge pro Seite                                                                          |
| `model`         | string  | max. Länge `100`                    | Angeforderter Name des angeforderten Modells                                                       |
| `modelVendor`   | string  | max. Länge `100`                    | Öffentlicher Modellanbieter                                                                        |
| `scene`         | enum    | -                                   | `chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime` |
| `accessChannel` | enum    | -                                   | `platform` oder `byok`                                                                             |
| `startDate`     | string  | -                                   | Inklusive Untergrenze; akzeptiert RFC3339 mit Zeitzone oder `YYYY-MM-DD`                           |
| `endDate`       | string  | -                                   | Inklusive Obergrenze; akzeptiert RFC3339 mit Zeitzone oder `YYYY-MM-DD`                            |

Wenn `startDate` und `endDate` zusammen angegeben werden, muss `startDate` kleiner oder gleich `endDate` sein.

## Hinweise

* Die Antwort ist paginiert.
* Die Antwort enthält nur öffentliche Reporting- und Billing-Felder.
* Sobald die zugrunde liegende Anfrage abgerechnet wurde, kann jede Usage-Zeile zusätzlich `billing_transaction_id` enthalten. Verwenden Sie den Wert zusammen mit `request_id` für den Abgleich auf Anfrageebene.
* Interne Routing- und physische Kanalmetadaten werden ausgeblendet.

## Beispiel

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

## Anfrage / Antwort

Verwenden Sie das interaktive OpenAPI-Panel oben für das genaue Schema und die Response-Felder.

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