El endpoint Usage devuelve una instantánea completa del consumo de créditos, el estado de suscripción, los límites de tasa y los metadatos de la clave API de su cuenta Piloterr. Úselo para monitorear su uso de forma programática y activar alertas o recargas antes de agotar sus créditos.
GET https://api.piloterr.com/v2/usage
Este endpoint no requiere parámetros de consulta. La autenticación se realiza mediante el encabezado x-api-key.
| Parámetro |
Tipo |
Requerido |
Descripción |
x-api-key |
string |
sí |
Su clave API privada de Piloterr |
| Campo |
Tipo |
Descripción |
remaining |
number |
Créditos restantes en la cuenta |
total_used |
number |
Total de créditos consumidos desde la creación de la cuenta |
renewal_date |
string | null |
Fecha de la próxima renovación de suscripción (ISO 8601) |
period.start |
string |
Fecha de inicio del período de facturación actual |
period.end |
string |
Fecha de fin del período de facturación actual |
subscription.used |
number |
Créditos de suscripción usados en el período actual |
subscription.total |
number |
Total de créditos de suscripción asignados por período |
subscription.remaining |
number |
Créditos de suscripción restantes en el período actual |
subscription.percent_used |
number |
Porcentaje de créditos de suscripción consumidos |
credits.given |
number |
Créditos bonus otorgados a la cuenta |
credits.consumed |
number |
Créditos bonus consumidos |
credits.remaining |
number |
Créditos bonus restantes |
credits.percent_used |
number |
Porcentaje de créditos bonus consumidos |
rate_limit.per_minute |
number | null |
Máximo de llamadas API por minuto (null = ilimitado) |
rate_limit.per_second |
number | null |
Máximo de llamadas API por segundo (null = ilimitado) |
account.name |
string |
Nombre de la cuenta Piloterr |
account.slug |
string |
Identificador slug de la cuenta |
api_key.alias |
string |
Alias legible de la clave API utilizada |
api_key.active |
boolean |
Indica si la clave API está actualmente activa |
api_key.category |
string |
Categoría de la clave API (ej. development, production) |
api_key.expires |
string | null |
Fecha de expiración de la clave API o null si no expira |
- Este endpoint requiere un encabezado
x-api-key válido. Las solicitudes sin clave devolverán 401 Unauthorized.
- Los valores
percent_used pueden superar 100 en escenarios de recarga o exceso.
- Los valores
rate_limit son null para planes sin limitación de tasa.
- Supervisar créditos restantes en tiempo real y activar flujos de recarga automática antes de agotar el cupo
- Construir dashboards internos que muestren el consumo de API por equipo o proyecto
- Configurar sistemas de alerta que notifiquen al equipo cuando el uso supere un umbral definido
- Validar el estado y la expiración de la clave API antes de ejecutar trabajos de datos en lote
