Obter uso da API Key

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

{
  "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",
      "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"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

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âmetro	Tipo	Padrões / limites	Descrição
`page`	integer	padrão `1`, mínimo `1`	Número da página começando em 1
`limit`	integer	padrão `50`, mínimo `1`, máximo `100`	Tamanho da página
`model`	string	comprimento máximo `100`	Nome do modelo solicitado
`modelVendor`	string	comprimento máximo `100`	Fornecedor público do modelo
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	Limite inferior inclusivo; aceita RFC3339 com fuso horário ou `YYYY-MM-DD`
`endDate`	string	-	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. Entradas em CNY foram descontinuadas e retornam 400 currency_retired.
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

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

Requisição / Resposta

Consulte o painel interativo de OpenAPI acima para ver o schema exato e os campos da resposta.

Exemplo de resposta

{
  "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",
      "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"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

Campos importantes

object

Resumo da chave de API com os mesmos campos das respostas de listagem, criação e atualização.

array

Linhas de uso paginadas.

object

Metadados de paginação com page, limit, total e totalPages.

object

Totais agregados para os filtros selecionados.

object

Detalhamentos agregados para os filtros selecionados.

string | null

Identificador público da solicitação para suporte e conciliação.

string | null

ID da transação de cobrança liquidada quando disponível.

string

Nome do modelo público solicitado.

string

Modelo público lógico usado para relatórios.

string | null

Fornecedor do modelo público.

string | null

Cenário da solicitação pública.

string

Unidade de uso de cobrança, como per_token.

number

Quantidade de uso como número JSON para exibição.

string

Quantidade de uso exata como string decimal.

number

Contagem de tokens do prompt.

number

Contagem de tokens de conclusão.

number

Contagem total de tokens.

number

Contagem de tokens lidos do cache.

number

Contagem total de tokens gravados no cache.

number

Contagem de tokens de gravação de cache de cinco minutos.

number

Contagem de tokens de gravação de cache de uma hora.

number

Custo em USD como número JSON para exibição.

string

Custo exato em USD como string decimal.

string

Carimbo de data/hora ISO da linha de uso.

number

Total de solicitações.

number

Custo total em USD como número JSON para exibição.

string

Custo total exato em USD como string decimal.

number

Contagem total de tokens do prompt.

number

Contagem total de tokens de conclusão.

number

Contagem total de tokens.

array

Quantidade de uso agrupada por unidade de uso.

array

Detalhamento por modelo público solicitado.

array

Detalhamento por modelo público lógico.

array

Detalhamento por fornecedor do modelo público.

array

Detalhamento por cenário da solicitação pública.

array

Tendência diária de custos.

Essencial

Texto

Arquivos e lotes

Imagens

Áudio e tempo real

Música

Vídeo e materiais

Worlds

3D

Tarefas assíncronas

Gemini nativo

Gerenciamento

Obter uso da API Key

Visão geral

Parâmetros de consulta

Observações

Exemplo

Requisição / Resposta

Exemplo de resposta

Campos importantes

​Visão geral

​Parâmetros de consulta

​Observações

​Exemplo

​Requisição / Resposta

​Exemplo de resposta

​Campos importantes

Visão geral

Parâmetros de consulta

Observações

Exemplo

Requisição / Resposta

Exemplo de resposta

Campos importantes