API Usage
Obtenha estatísticas de uso em tempo real e o saldo de créditos da sua conta Piloterr.
Visão Geral do Endpoint
Documentação detalhada, preços e exemplos de uso.
Visão geralLink to Visão geral
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.
Início rápidoLink to Início rápido
GET https://api.piloterr.com/v2/usage
ParâmetrosLink to Parâmetros
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 |
Campos de respostaLink to Campos de resposta
| 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 |
packs |
object | null | Packs API pontuais, pack a pack (null se a conta não tiver nenhum). Em contas sem plano mensal, subscription.total é a soma de todos os packs |
packs.count |
number | Número de packs ativos |
packs.exhausted_count |
number | Número de packs totalmente consumidos |
packs.total |
number | Créditos concedidos por todos os packs ativos |
packs.used |
number | Créditos consumidos em todos os packs |
packs.remaining |
number | Créditos restantes em todos os packs |
packs.current |
object | null | O pack em consumo (os packs são usados por ordem de compra); null quando todos estão esgotados |
packs.items[] |
object[] | Cada pack ativo: id, title, purchased_at, total, used, remaining, percent_used, exhausted |
SaldosLink to Saldos
Cada chamada consome de até três saldos, sempre por esta ordem. A resposta detalha cada um separadamente para que saiba de onde vêm os seus créditos.
- Quota de subscrição (
subscription): chamadas incluídas num plano mensal. Reposta a cada período de faturação (period,renewal_date). - Packs API pontuais (
packs): comprados uma vez, nunca repostos, consumidos por ordem de compra quando a quota mensal se esgota.packs.currenté o pack em uso agora; cada item mostra os seus própriosusederemaining. Em contas sem plano mensal,subscriptionreporta a soma de todos os packs. - Créditos pay-as-you-go (
credits): usados apenas quando quota e packs estão esgotados. Faturados à parte.
remaining é o total ainda disponível nos três saldos e total_used o total consumido. Quando remaining chega a 0, as chamadas devolvem 402 até ser adicionado um pack ou créditos.
NotasLink to Notas
- Este endpoint requer um cabeçalho
x-api-keyválido. Requisições sem chave retornarão401 Unauthorized. - Valores
percent_usedpodem exceder 100 em cenários de recarga ou excesso. - Valores
rate_limitsãonullpara planos sem limitação de taxa.
Principais casos de usoLink to Principais casos de uso
- 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
Pronto para começar?
Sua API de web scraping está a um clique. Comece com +500 créditos, sem infraestrutura para configurar, sem proxies para gerenciar e sem cartão de crédito necessário.
- +500 créditos
- Sem cartão de crédito
- Todos os endpoints incluídos