Administración

Obtener uso de API Key

Devuelve detalles de uso paginados para una API key de usuario.

GEThttps://api.tokenlab.sh/v1/management/api-keys/{keyId}/usage

Descripción general

Devuelve registros de uso paginados para una API key.

Parámetros de consulta

ParámetroTipoPredeterminado / LímitesNotas
pageintegerpredeterminado 1, mín 1Número de página basado en 1
limitintegerpredeterminado 50, mín 1, máx 100Tamaño de página
modelstringlongitud máx 100Nombre del modelo solicitado
modelVendorstringlongitud máx 100Proveedor del modelo público
sceneenum-chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime, systemone
startDatestring-Límite inferior inclusivo; acepta RFC3339 con zona horaria o YYYY-MM-DD (00:00 UTC)
endDatestring-Límite superior inclusivo; acepta RFC3339 con zona horaria o YYYY-MM-DD. Un valor de solo fecha significa 00:00 UTC al inicio de ese día, por lo que para incluir un día completo, use la fecha siguiente o una hora RFC3339

Si tanto startDate como endDate están presentes, startDate debe ser anterior o igual a endDate.

Notas

  • Los campos monetarios están solo en USD.

  • La respuesta está paginada.

  • Los registros liquidados pueden incluir billing_transaction_id. Guárdelo junto con request_id cuando necesite hacer coincidir un cargo con una solicitud.

  • Los registros están ordenados por created_at, los más recientes primero.

  • Un error 429 con el código report_busy significa que la cola de informes está llena. Vuelva a intentarlo después de los segundos indicados en Retry-After.

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-31T23:59:59Z" \
  -H "Authorization: Bearer mt-your-management-token"

Solicitud / Respuesta

Esta página proporciona el esquema OpenAPI y ejemplos de solicitud que se pueden copiar. Envíe solicitudes de gestión desde su terminal o cliente con un Management Token; el envío directo no está disponible en esta página.

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-sonnet-4-6"
    ],
    "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 API key utilizando los mismos campos que las respuestas de listado/creación/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 utilizado 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 de lectura de caché.
items[].cache_write_tokensnumber
Recuento total de tokens de escritura de 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
Costo en USD como número JSON para visualización.
items[].cost_decimalstring
Costo exacto en USD como cadena decimal.
items[].requested_policystring | null
auto, verified, official, null. Política de entrega solicitada, cuando se registra.
items[].resolved_tierstring | null
verified, official, null. Nivel de entrega utilizado, cuando se registra.
items[].charged_price_basisobject | null
Precio aplicado y cantidad facturable, cuando se registra. Para una solicitud con tarifas de herramientas, measure.dimensions incluye webSearchCalls o groundedPrompts, y effectiveUnitPrices incluye el precio de cada llamada como webSearch o groundedPrompt.
items[].created_atstring
Marca de tiempo ISO de la fila de uso.
summary.total_requestsnumber
Recuento total de solicitudes.
summary.total_costnumber
Costo total en USD como número JSON para visualización.
summary.total_cost_decimalstring
Costo total exacto en USD como cadena decimal.
summary.total_prompt_tokensnumber
Total de tokens de prompt.
summary.total_completion_tokensnumber
Total de tokens de finalización.
summary.total_tokensnumber
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 de modelo público.
breakdowns.by_scenearray
Desglose por escena de solicitud pública.
breakdowns.daily_costarray
Tendencia de costo diario.

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

Límite inferior, inclusivo. Acepta RFC3339 con zona horaria (por ejemplo, 2026-03-28T00:00:00+08:00) o YYYY-MM-DD, que significa 00:00 UTC.

endDate?string

Límite superior, inclusivo. Acepta RFC3339 con zona horaria (por ejemplo, 2026-03-28T23:59:59+08:00) o YYYY-MM-DD, que significa 00:00 UTC al inicio de ese día. Para incluir un día completo, pase la fecha del día siguiente o una hora RFC3339 al final del día.

Respuesta

application/json

application/json

application/json

application/json

application/json

application/json