O endpoint Usage retorna um instantâneo completo do consumo de créditos, status de assinatura, limites de taxa e metadados da chave de API da sua conta Piloterr. Use-o para monitorar seu uso de forma programática e acionar alertas ou recargas antes de esgotar seus créditos.
GET https://api.piloterr.com/v2/usage
Este endpoint não requer parâmetros de consulta. A autenticação é feita via cabeçalho x-api-key.
| Parâmetro |
Tipo |
Obrigatório |
Descrição |
x-api-key |
string |
sim |
Sua chave de API privada Piloterr |
| Campo |
Tipo |
Descrição |
remaining |
number |
Créditos restantes na conta |
total_used |
number |
Total de créditos consumidos desde a criação da conta |
renewal_date |
string | null |
Data da próxima renovação da assinatura (ISO 8601) |
period.start |
string |
Data de início do período de cobrança atual |
period.end |
string |
Data de fim do período de cobrança atual |
subscription.used |
number |
Créditos de assinatura usados no período atual |
subscription.total |
number |
Total de créditos de assinatura alocados por período |
subscription.remaining |
number |
Créditos de assinatura restantes no período atual |
subscription.percent_used |
number |
Percentual de créditos de assinatura consumidos |
credits.given |
number |
Créditos bônus concedidos à conta |
credits.consumed |
number |
Créditos bônus consumidos |
credits.remaining |
number |
Créditos bônus restantes |
credits.percent_used |
number |
Percentual de créditos bônus consumidos |
rate_limit.per_minute |
number | null |
Máximo de chamadas de API por minuto (null = ilimitado) |
rate_limit.per_second |
number | null |
Máximo de chamadas de API por segundo (null = ilimitado) |
account.name |
string |
Nome da conta Piloterr |
account.slug |
string |
Identificador slug da conta |
api_key.alias |
string |
Alias legível da chave de API utilizada |
api_key.active |
boolean |
Indica se a chave de API está atualmente ativa |
api_key.category |
string |
Categoria da chave de API (ex. development, production) |
api_key.expires |
string | null |
Data de expiração da chave de API ou null se não expirar |
- Este endpoint requer um cabeçalho
x-api-key válido. Requisições sem chave retornarão 401 Unauthorized.
- Valores
percent_used podem exceder 100 em cenários de recarga ou excesso.
- Valores
rate_limit são null para planos sem limitação de taxa.
- Monitorar créditos restantes em tempo real e acionar fluxos de recarga automática antes de esgotar o saldo
- Construir dashboards internos que exibam o consumo de API por equipe ou projeto
- Configurar sistemas de alerta que notifiquem a equipe quando o uso ultrapassar um limite definido
- Validar o status e a expiração da chave de API antes de executar trabalhos de dados em lote
