Monitorar Uso da API

Retorna informações detalhadas sobre o consumo da sua cota mensal de chamadas de API, status do seu plano atual e previsões de reset.

Endpoint

| GET | /api/v1/usage | Sim (Bearer) |

URL Completa: https://botgate-api-987684559046.us-central1.run.app/api/v1/usage

Resposta de Sucesso

{
  "success": true,
  "data": {
    "bot": {
      "id": "1234567890123456789",
      "name": "BotTeste"
    },
    "tier": {
      "name": "free",
      "displayName": "Free",
      "features": {
        "customWebhooks": false,
        "prioritySupport": false,
        "badge": "none"
      }
    },
    "usage": {
      "apiCalls": {
        "used": 1,
        "limit": 1500,
        "remaining": 1499,
        "percentage": 0.07,
        "status": "healthy",
        "message": "Uso normal"
      },
      "reset": {
        "at": "2026-02-24T03:17:47.000Z",
        "inDays": 31,
        "inHours": 743
      }
    },
    "updates": {
      "interval": "30 minutes",
      "lastUpdate": "2026-01-24T04:17:06.000Z",
      "nextUpdateAllowedAt": "2026-01-24T04:47:06.000Z",
      "minutesUntilNextUpdate": 0,
      "canUpdateNow": true
    },
    "capabilities": {
      "analyticsLevel": "basic",
      "historyDays": 7,
      "updateIntervalMinutes": 30
    },
    "statistics": {
      "avgCallsPerDay": 0,
      "estimatedDaysRemaining": 31,
      "usageHistory": []
    },
    "upgrade": null
  }
}

Informações Retornadas

1. Cota de Chamadas: Acompanhe em tempo real quantas chamadas de API (POST /stats, GET /votes, etc) você já realizou no mês.
2. Previsão de Reset: Saiba exatamente quando seu contador de chamadas voltará a zero (baseado em ciclos de 30 dias).
3. Controle de Intervalo: Verifique se você já pode enviar um novo relatório de estatísticas ou se ainda está no período de espera (cooldown) do seu plano.
4. Status de Saúde: Receba alertas automáticos (healthy, warning, critical) caso seu uso esteja próximo do limite.

Por que monitorar?

Pacote NPM

Você pode consultar todo o seu consumo de API usando o método reporter.getApiUsage().

Este endpoint é fundamental para evitar que seu bot pare de enviar estatísticas por falta de cota. Recomendamos consultar este endpoint uma vez por dia ou salvar o valor de percentage para alertar sua equipe administrativa.