Consultar uso — GET /v1/usage

Retorna o saldo atual de créditos da organização e o consumo do ciclo vigente — útil para integrações que precisam checar saldo antes de disparar mensagens em massa, por exemplo.

Requisito

Exige um token com escopo agents:read. Tokens de widget (vinculados a um único agente) não têm acesso a esta rota — retorna 403 Forbidden, já que ela expõe dados da organização inteira, não de um agente específico.

Requisição

GET /v1/usage
Authorization: Bearer f2a_live_...

Resposta

{
  "credits_balance": 87,
  "period_start": "2026-07-01T00:00:00.000Z",
  "period_end": "2026-08-01T00:00:00.000Z",
  "credits_spent": 143,
  "messages_count": 62
}

credits_spent e messages_count somam o período de cobrança atual (desde period_start) — os mesmos números mostrados em Configurações → Assinatura e créditos (veja Como funcionam os créditos), só que acessíveis programaticamente.