Uso e custo

Quanto você usou, contra quais limites, e quanto custou. Todos estes endpoints são GET, exigem a sua chave de API e só descrevem a sua própria conta.

O que conta#

O uso é lido do registro que o gateway guarda de toda chamada a um modelo, em todas as superfícies: os endpoints /v1, os endpoints de chat nativos e os apps. Só as chamadas bem-sucedidas contam. Uma chamada recusada, ou que falhou, não acrescenta nada. Embeddings e áudio não são contados.

Um token é contado uma vez: tokens de entrada mais tokens de saída formam total_tokens. Os modelos dos servidores do próprio operador contam, assim como os modelos de nuvem.

GET/api/v1/usage#

As janelas da sua cota de tokens. É a chamada certa para um medidor de uso ou para uma checagem antes de um lote de trabalho.

{
  "today": { "used": 19, "limit": 1000000, "remaining": 999981, "reset_at": "2026-10-11T00:00:00+00:00" },
  "week":  { "used": 19, "limit": 7000000, "remaining": 6999981, "reset_at": "2026-10-14T14:00:00+00:00" },
  "month": { "used": 19, "limit": 15000000, "remaining": 14999981, "reset_at": "2026-11-01T00:00:00+00:00" }
}

• limit é definido pelo operador para o grupo da sua conta. Um limite de -1 quer dizer sem limite, e remaining é então null.
• As janelas são em UTC: o dia zera à meia-noite, o mês no primeiro dia, e a semana na quarta-feira às 14:00. No fim de um mês, quando o mês seguinte é mais curto, month.reset_at pode mostrar uma data com um mês de atraso: o mês em si sempre zera no primeiro dia.
• remaining não desconta a reserva que uma chamada em andamento faz, então, com carga em paralelo, o gateway pode recusar uma chamada um pouco antes do que remaining sugere.

Quando um limite é atingido, as chamadas são recusadas com 403. Veja limites e cotas.

GET/api/v1/usage/resumo#

Um resumo de um período. A query periodo é 30d (o padrão), 90d ou ano, e qualquer outro valor quer dizer 30 dias.

A resposta tem chaves em português, por razões históricas. As partes importantes:

Dois cuidados. usd mistura o custo informado pelos provedores com uma estimativa de uma tabela de preços, e deixa de fora os tokens que não têm preço, como os dos modelos do próprio operador: "sem preço" não é "de graça", então leia tokens_sem_preco ao lado. E por_origem[].origem é um rótulo que muda com o seu idioma: use o codigo dele.

GET/api/v1/usage/providers#

O gasto por provedor de nuvem, para hoje, esta semana, este mês e no total (o total cobre o período de retenção dos registros, 180 dias por padrão).

{
  "currency": "USD",
  "show_brl": true,
  "usd_brl": 5.4,
  "windows": {
    "month": {
      "providers": [
        { "server_key": "anthropic", "label": "Anthropic (nuvem)", "tokens_in": 120000, "tokens_out": 18000, "requests": 64, "est_cost_usd": 0.63, "has_real_cost": false, "unpriced_tokens": 0 }
      ],
      "est_cost_usd_total": 0.63,
      "unpriced_tokens_total": 0
    }
  },
  "live_balances": {}
}

est_cost_usd é o custo que o provedor informou, quando há um, e, no resto dos casos, os tokens vezes a tabela de preços; has_real_cost diz qual dos dois. Quando unpriced_tokens é maior que 0, o custo está incompleto. Os servidores do próprio operador não são listados.

live_balances pergunta a cada provedor o seu saldo restante, com a sua chave. Só funciona para os provedores que oferecem uma chamada de saldo, e pode deixar este endpoint lento com o cache frio.

GET/api/v1/conversations/{id}/usage#

Os tokens e o custo de uma conversa guardada:

{
  "status": "success",
  "data": {
    "conversation_id": 3,
    "prompt_tokens": 24,
    "completion_tokens": 7,
    "total_tokens": 19,
    "assistant_replies": 1,
    "cost_real_usd": 0,
    "cost_estimated_usd": 0,
    "cost_total_usd": 0,
    "models": ["claude-sonnet-4-6"]
  }
}

cost_real_usd soma o que os provedores informaram. cost_estimated_usd soma as estimativas da tabela de preços. Os números são arredondados em 6 casas decimais.

Use total_tokens como os tokens medidos da conversa. prompt_tokens soma o prompt de cada mensagem guardada, incluindo a cópia que fica na sua própria pergunta, então conta cada prompt duas vezes e cresce com o histórico. É por isso que pode ser maior que o total_tokens ao lado.

Outros endpoints#

GET /api/v1/usage/apibar dá o custo do mês e de hoje por provedor para uma barra de status, e tem a mesma ressalva sobre o saldo. GET /api/v1/usage/daily-ring e GET /api/v1/usage/savings servem aos apps e não são descritos aqui.

O custo em cada chamada#

O custo de uma resposta vem na própria resposta, no stream do chat nativo: usage.cost e usage.cost_estimated. Os endpoints /v1 informam só tokens, em usage.