TokenLab
Obter chave de API
DocumentaçãoReferência da APIIntegrações

Gerenciamento

Obter uso da API Key

Retorna o detalhamento paginado de uso para uma API Key de usuário.

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

Visão geral

Este endpoint retorna o detalhamento de uso por API Key sem expor metadata de roteamento físico.

Parâmetros de consulta

ParâmetroTipoPadrões / limitesDescrição
pageintegerpadrão 1, mínimo 1Número da página começando em 1
limitintegerpadrão 50, mínimo 1, máximo 100Tamanho da página
modelstringcomprimento máximo 100Nome do modelo solicitado
modelVendorstringcomprimento máximo 100Fornecedor público do modelo
sceneenum-chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime
startDatestring-Limite inferior inclusivo; aceita RFC3339 com fuso horário ou YYYY-MM-DD
endDatestring-Limite superior inclusivo; aceita RFC3339 com fuso horário ou YYYY-MM-DD

Se startDate e endDate forem enviados juntos, startDate deve ser anterior ou igual a endDate.

Observações

  • Os campos monetários aceitam apenas USD.

  • A resposta é paginada.

  • A resposta inclui apenas campos públicos de faturamento e reporting.

  • Cada item de usage também pode incluir billing_transaction_id depois que a requisição subjacente atingir o estado de liquidação concluída. Use esse valor junto com request_id para reconciliação por requisição.

  • A metadata de roteamento interno e dos canais físicos permanece oculta de forma intencional.

Exemplo

Requisição

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"

Requisição / Resposta

Esta página fornece o esquema OpenAPI e exemplos de requisições para copiar. Envie solicitações de gerenciamento pelo terminal ou cliente usando um Management Token; o envio direto não está disponível nesta página.

Exemplo de resposta

Resposta

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
Resumo da chave de API com os mesmos campos das respostas de listagem, criação e atualização.
itemsarray
Linhas de uso paginadas.
paginationobject
Metadados de paginação com page, limit, total e totalPages.
summaryobject
Totais agregados para os filtros selecionados.
breakdownsobject
Detalhamentos agregados para os filtros selecionados.
items[].request_idstring | null
Identificador público da solicitação para suporte e conciliação.
items[].billing_transaction_idstring | null
ID da transação de cobrança liquidada quando disponível.
items[].modelstring
Nome do modelo público solicitado.
items[].logical_modelstring
Modelo público lógico usado para relatórios.
items[].model_vendorstring | null
Fornecedor do modelo público.
items[].scenestring | null
Cenário da solicitação pública.
items[].usage_unitstring
Unidade de uso de cobrança, como per_token.
items[].usage_quantitynumber
Quantidade de uso como número JSON para exibição.
items[].usage_quantity_decimalstring
Quantidade de uso exata como string decimal.
items[].prompt_tokensnumber
Contagem de tokens do prompt.
items[].completion_tokensnumber
Contagem de tokens de conclusão.
items[].total_tokensnumber
Contagem total de tokens.
items[].cache_read_tokensnumber
Contagem de tokens lidos do cache.
items[].cache_write_tokensnumber
Contagem total de tokens gravados no cache.
items[].cache_write_tokens_5mnumber
Contagem de tokens de gravação de cache de cinco minutos.
items[].cache_write_tokens_1hnumber
Contagem de tokens de gravação de cache de uma hora.
items[].costnumber
Custo em USD como número JSON para exibição.
items[].cost_decimalstring
Custo exato em USD como string decimal.
items[].requested_policystring | null
auto, verified, official, null. Política de entrega solicitada, quando registrada.
items[].resolved_tierstring | null
verified, official, null. Nível de entrega utilizado, quando registrado.
items[].charged_price_basisobject | null
Preço aplicado e quantidade faturável, quando registrados.
items[].created_atstring
Carimbo de data/hora ISO da linha de uso.
summary.total_requestsnumber
Total de solicitações.
summary.total_costnumber
Custo total em USD como número JSON para exibição.
summary.total_cost_decimalstring
Custo total exato em USD como string decimal.
summary.total_prompt_tokensnumber
Contagem total de tokens do prompt.
summary.total_completion_tokensnumber
Contagem total de tokens de conclusão.
summary.total_tokensnumber
Contagem total de tokens.
summary.usage_unit_breakdownarray
Quantidade de uso agrupada por unidade de uso.
breakdowns.by_modelarray
Detalhamento por modelo público solicitado.
breakdowns.by_logical_modelarray
Detalhamento por modelo público lógico.
breakdowns.by_model_vendorarray
Detalhamento por fornecedor do modelo público.
breakdowns.by_scenearray
Detalhamento por cenário da solicitação pública.
breakdowns.daily_costarray
Tendência diária de custos.

Autorização

ManagementTokenAuth
AuthorizationBearer <token>

Autenticação por token de gerenciamento. Crie ou gerencie Tokens de Gerenciamento em Dashboard > API > Management Tokens.

Local: header

Parâmetros de caminho

keyId*string

Parâmetros de consulta

page?integer

Número da página baseado em 1. O padrão é 1.

Intervalo1 <= value
padrão1
limit?integer

Tamanho da página. O padrão é 50 e o máximo é 100.

Intervalo1 <= value <= 100
padrão50
model?string

Filtrar pelo nome do modelo solicitado. Comprimento máximo de 100.

Comprimentolength <= 100
modelVendor?string

Filtrar pelo fornecedor do modelo público. Comprimento máximo de 100.

Comprimentolength <= 100
scene?string

Filtrar por cena de solicitação pública.

Valores permitidos

  • "chat"
  • "image"
  • "audio"
  • "video"
  • "embedding"
  • "rerank"
  • "translation"
  • "music"
  • "3d"
  • "realtime"
  • "systemone"
startDate?string

Filtro de data inclusivo. Aceita RFC3339 com fuso horário (por exemplo, 2026-03-28T00:00:00+08:00) ou YYYY-MM-DD.

endDate?string

Filtro de data inclusivo. Aceita RFC3339 com fuso horário (por exemplo, 2026-03-28T00:00:00+08:00) ou YYYY-MM-DD.

Resposta

application/json

application/json

application/json

application/json

application/json

Atualizar API Key

Anterior

Obter faturamento da chave API

Próxima