---
title: "Get API key usage"
method: GET
path: "/v1/management/api-keys/{keyId}/usage"
tags: ["Management"]
---

# Get API key usage

`GET /v1/management/api-keys/{keyId}/usage`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/v1/management/api-keys/{keyId}/usage`
- Auth: HTTP bearer

Returns paginated usage details for this API key.

## Path parameters

- `keyId` string, required

## Query parameters

- `page` integer
- `limit` integer
- `model` string
- `modelVendor` string
- `scene` 'chat' | 'image' | 'audio' | 'video' | 'embedding' | 'rerank' | 'translation' | 'music' | '3d' | 'realtime' | 'systemone'
- `startDate` string
- `endDate` string

## Response `200`

API key usage details

- ManagementUsageResponse
  - `api_key` ManagementApiKey, required
    - `id` string, required
    - `name` string, required
    - `key_prefix` string, required
    - `status` 'active' | 'inactive' | 'suspended' | 'revoked', required: Lifecycle status for the user API key: active, inactive, or revoked.
    - `limit_amount` number, nullable, required: API key spending cap in USD as a JSON number for display. null means unlimited.
    - `used_amount` number, required: Accumulated API key usage in USD as a JSON number for display.
    - `models` string[], required
    - `expires_at` string, date-time, nullable, required
    - `last_used_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
    - `key` string: Returned only on creation
    - `limit_amount_decimal` string, nullable, required: Exact API key spending cap in USD as a decimal string. null means unlimited.
    - `used_amount_decimal` string, required: Exact accumulated API key usage in USD as a decimal string for reconciliation.
    - `delivery_policy` 'auto' | 'verified' | 'official' | 'null', nullable, required: Per-key Delivery policy. null inherits the Workspace default.
  - `items` ManagementUsageItem[], required
    - `request_id` string, nullable, required
    - `billing_transaction_id` string, nullable, required: Settled billing transaction id for request-level reconciliation.
    - `model_vendor` string, nullable, required
    - `scene` string, nullable, required
    - `usage_unit` string, required
    - `usage_quantity` number, required
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
    - `cache_read_tokens` integer, required
    - `cache_write_tokens` integer, required
    - `cost` number, required: Request cost in USD as a JSON number for display.
    - `created_at` string, date-time, required
    - `model` string, required
    - `logical_model` string, required
    - `usage_quantity_decimal` string, required: Exact usage quantity as a decimal string for non-token units.
    - `cache_write_tokens_5m` integer, required
    - `cache_write_tokens_1h` integer, required
    - `cost_decimal` string, required: Exact request cost in USD as a decimal string for reconciliation.
    - `requested_policy` 'auto' | 'verified' | 'official' | 'null', nullable, required
    - `resolved_tier` 'verified' | 'official' | 'null', nullable, required
    - `charged_price_basis` ChargedPriceBasis, required
      - `version` 1, required
      - `resolvedTier` 'verified' | 'official', required
      - `priceVersion` string, required
      - `measure` object, required
        - `unit` string, required
        - `quantity` string, required
        - `dimensions` object, required
      - `effectiveUnitPrices` object, required
        - `unit` string, required
        - `input` string, nullable
        - `output` string, nullable
        - `cacheRead` string, nullable
        - `cacheWrite` string, nullable
        - `cacheWrite1h` string, nullable
        - `fixed` string, nullable
        - `webSearch` string, nullable
        - `groundedPrompt` string, nullable
        - `structured` object, nullable
  - `pagination` object, required
    - `page` integer, required
    - `limit` integer, required
    - `total` integer, required
    - `totalPages` integer, required
  - `summary` ManagementUsageSummary, required
    - `total_requests` integer, required
    - `total_cost` number, required: Aggregated total cost in USD as a JSON number for display.
    - `total_prompt_tokens` integer, required
    - `total_completion_tokens` integer, required
    - `total_tokens` integer, required
    - `usage_unit_breakdown` object[], required
      - `usage_unit` string, required
      - `usage_quantity` number, required
    - `total_cost_decimal` string, required: Exact aggregated total cost in USD as a decimal string for reconciliation.
  - `breakdowns` ManagementBreakdowns, required
    - `by_model_vendor` ManagementModelVendorBreakdown[]
      - `model_vendor` string, required
      - `requests` integer, required
      - `cost` number, required: Cost in USD as a JSON number for display.
    - `by_scene` ManagementSceneBreakdown[]
      - `scene` string, nullable, required
      - `requests` integer, required
      - `cost` number, required: Cost in USD as a JSON number for display.
      - `cost_decimal` string, required: Exact cost in USD as a decimal string for reconciliation.
    - `daily_cost` ManagementDailyCostBreakdown[]
      - `date` string, date-time, required
      - `cost` number, required: Cost in USD as a JSON number for display.
      - `cost_decimal` string, required: Exact cost in USD as a decimal string for reconciliation.
    - `by_model` ManagementModelBreakdown[]
      - `model_vendor` string, nullable, required
      - `requests` integer, required
      - `cost` number, required: Cost in USD as a JSON number for display.
      - `usage_quantity` number, required
      - `model` string, required
      - `logical_model` string, required
      - `cost_decimal` string, required: Exact cost in USD as a decimal string for reconciliation.
      - `usage_quantity_decimal` string, required
    - `by_logical_model` ManagementModelBreakdown[]
      - `model_vendor` string, nullable, required
      - `requests` integer, required
      - `cost` number, required: Cost in USD as a JSON number for display.
      - `usage_quantity` number, required
      - `model` string, required
      - `logical_model` string, required
      - `cost_decimal` string, required: Exact cost in USD as a decimal string for reconciliation.
      - `usage_quantity_decimal` string, required

## Other responses

- `400`: Bad Request - Invalid input
- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden
- `404`: Not Found

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)