Obtener uso de API Key

Resumen

Este endpoint devuelve el detalle de uso por API Key sin exponer metadata de routing físico.

Parámetros de consulta

Parámetro	Tipo	Valores por defecto / límites	Descripción
`page`	integer	valor por defecto `1`, mínimo `1`	Número de página empezando en 1
`limit`	integer	valor por defecto `50`, mínimo `1`, máximo `100`	Tamaño de página
`model`	string	longitud máxima `100`	Nombre del modelo solicitado
`modelVendor`	string	longitud máxima `100`	Proveedor público del modelo
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	Límite inferior inclusivo; acepta RFC3339 con zona horaria o `YYYY-MM-DD`
`endDate`	string	-	Límite superior inclusivo; acepta RFC3339 con zona horaria o `YYYY-MM-DD`

Si startDate y endDate se envían a la vez, startDate debe ser anterior o igual a endDate.

Notas

Los campos monetarios solo admiten USD.
La respuesta está paginada.
La respuesta solo incluye campos públicos de facturación y reporting.
Cada registro de uso también puede incluir billing_transaction_id una vez que la solicitud subyacente haya quedado liquidada. Úsalo junto con request_id para la conciliación a nivel de solicitud.
La metadata de routing interno y de canales físicos permanece oculta de forma intencional.

Ejemplo

Solicitud

cURL

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=chat&startDate=2026-07-01&endDate=2026-07-31" \
  -H "Authorization: Bearer mt-your-management-token"

Esta página ofrece el esquema OpenAPI y ejemplos de solicitudes que puedes copiar. Envía las solicitudes de gestión desde tu terminal o cliente con un Management Token; esta página no permite enviarlas directamente.

Ejemplo de respuesta

Respuesta

200 OK

{
  "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.6-luna",
      "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",
    "delivery_policy": null
  },
  "items": [
    {
      "request_id": "req_abc123",
      "billing_transaction_id": "billtxn_abc123",
      "model": "gpt-5.6-luna",
      "logical_model": "gpt-5.6-luna",
      "model_vendor": "OpenAI",
      "scene": "chat",
      "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",
      "requested_policy": null,
      "resolved_tier": null,
      "charged_price_basis": null
    }
  ],
  "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.6-luna",
        "logical_model": "gpt-5.6-luna",
        "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.6-luna",
        "logical_model": "gpt-5.6-luna",
        "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"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

Campos importantes

api_keyobject

Resumen de la clave API con los mismos campos que las respuestas de listado, creación y actualización.

itemsarray

Filas de uso paginadas.

paginationobject

Metadatos de paginación con page, limit, total y totalPages.

summaryobject

Totales agregados para los filtros seleccionados.

breakdownsobject

Desgloses agregados para los filtros seleccionados.

items[].request_idstring | null

Identificador público de solicitud para soporte y conciliación.

items[].billing_transaction_idstring | null

ID de transacción de facturación liquidada cuando esté disponible.

items[].modelstring

Nombre del modelo público solicitado.

items[].logical_modelstring

Modelo público lógico usado para informes.

items[].model_vendorstring | null

Proveedor del modelo público.

items[].scenestring | null

Escena de solicitud pública.

items[].usage_unitstring

Unidad de uso de facturación, como per_token.

items[].usage_quantitynumber

Cantidad de uso como número JSON para visualización.

items[].usage_quantity_decimalstring

Cantidad de uso exacta como cadena decimal.

items[].prompt_tokensnumber

Recuento de tokens de prompt.

items[].completion_tokensnumber

Recuento de tokens de finalización.

items[].total_tokensnumber

Recuento total de tokens.

items[].cache_read_tokensnumber

Recuento de tokens leídos de la caché.

items[].cache_write_tokensnumber

Recuento total de tokens escritos en la caché.

items[].cache_write_tokens_5mnumber

Recuento de tokens de escritura de caché de cinco minutos.

items[].cache_write_tokens_1hnumber

Recuento de tokens de escritura de caché de una hora.

items[].costnumber

Coste en USD como número JSON para visualización.

items[].cost_decimalstring

Coste exacto en USD como cadena decimal.

items[].requested_policystring | null

auto, verified, official, null. Política de entrega solicitada, si se registró.

items[].resolved_tierstring | null

verified, official, null. Nivel de entrega utilizado, si se registró.

items[].charged_price_basisobject | null

Precio aplicado y cantidad facturable, si se registraron.

items[].created_atstring

Marca de tiempo ISO de la fila de uso.

summary.total_requestsnumber

Número total de solicitudes.

summary.total_costnumber

Coste total en USD como número JSON para visualización.

summary.total_cost_decimalstring

Coste total exacto en USD como cadena decimal.

summary.total_prompt_tokensnumber

Recuento total de tokens de prompt.

summary.total_completion_tokensnumber

Recuento total de tokens de finalización.

summary.total_tokensnumber

Recuento total de tokens.

summary.usage_unit_breakdownarray

Cantidad de uso agrupada por unidad de uso.

breakdowns.by_modelarray

Desglose por modelo público solicitado.

breakdowns.by_logical_modelarray

Desglose por modelo público lógico.

breakdowns.by_model_vendorarray

Desglose por proveedor del modelo público.

breakdowns.by_scenearray

Desglose por escena de solicitud pública.

breakdowns.daily_costarray

Tendencia diaria del coste.

Autorización

ManagementTokenAuth

AuthorizationBearer <token>

Autenticación con Management Token. Cree o gestione Management Tokens en Dashboard > API > Management Tokens.

Ubicación: header

Parámetros de ruta

keyId*string

Parámetros de consulta

page?integer

Número de página basado en 1. El valor predeterminado es 1.

Rango1 <= value

predeterminado1

limit?integer

Tamaño de página. El valor predeterminado es 50 y el máximo es 100.

Rango1 <= value <= 100

predeterminado50

model?string

Filtrar por nombre de modelo solicitado. Longitud máxima 100.

Longitudlength <= 100

modelVendor?string

Filtrar por proveedor de modelo público. Longitud máxima 100.

Longitudlength <= 100

scene?string

Filtrar por escena de solicitud pública.

Valores permitidos

"chat"
"image"
"audio"
"video"
"embedding"
"rerank"
"translation"
"music"
"3d"
"realtime"
"systemone"

startDate?string

Filtro de fecha inclusivo. Acepta RFC3339 con zona horaria (por ejemplo, 2026-03-28T00:00:00+08:00) o YYYY-MM-DD.

endDate?string

Filtro de fecha inclusivo. Acepta RFC3339 con zona horaria (por ejemplo, 2026-03-28T00:00:00+08:00) o YYYY-MM-DD.

Obtener uso de API Key

Resumen

Parámetros de consulta

Notas

Ejemplo

Solicitud / Respuesta

Ejemplo de respuesta

Campos importantes

Autorización

Parámetros de ruta

Parámetros de consulta

Respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Obtener uso de API Key

ResumenCopy Anchor Link

Parámetros de consultaCopy Anchor Link

NotasCopy Anchor Link

EjemploCopy Anchor Link

Solicitud / RespuestaCopy Anchor Link

Ejemplo de respuestaCopy Anchor Link

Campos importantesCopy Anchor Link

AutorizaciónCopy Anchor Link

Parámetros de rutaCopy Anchor Link

Parámetros de consultaCopy Anchor Link

RespuestaCopy Anchor Link

200application/json

400application/json

401application/json

403application/json

404application/json

Resumen

Parámetros de consulta

Notas

Ejemplo

Solicitud / Respuesta

Ejemplo de respuesta

Campos importantes

Autorización

Parámetros de ruta

Parámetros de consulta

Respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`