API de Usage
Obtenga estadísticas de uso en tiempo real y el saldo de créditos de su cuenta Piloterr.
Resumen del Endpoint
Documentación detallada, precios y ejemplos de uso.
Descripción generalLink to Descripción general
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.
Inicio rápidoLink to Inicio rápido
GET https://api.piloterr.com/v2/usage
ParámetrosLink to Parámetros
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 |
Campos de respuestaLink to Campos de respuesta
| 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 |
packs |
object | null | Packs API puntuales, pack por pack (null si la cuenta no tiene ninguno). En cuentas sin plan mensual, subscription.total es la suma de todos los packs |
packs.count |
number | Número de packs activos |
packs.exhausted_count |
number | Número de packs totalmente consumidos |
packs.total |
number | Créditos otorgados por todos los packs activos |
packs.used |
number | Créditos consumidos en todos los packs |
packs.remaining |
number | Créditos restantes en todos los packs |
packs.current |
object | null | El pack que se está consumiendo (los packs se usan en orden de compra); null cuando todos están agotados |
packs.items[] |
object[] | Cada pack activo: id, title, purchased_at, total, used, remaining, percent_used, exhausted |
SaldosLink to Saldos
Cada llamada consume de hasta tres saldos, siempre en este orden. La respuesta detalla cada uno por separado para que sepa de dónde salen sus créditos.
- Cuota de suscripción (
subscription): llamadas incluidas en un plan mensual. Se reinicia en cada periodo de facturación (period,renewal_date). - Packs API puntuales (
packs): se compran una vez, nunca se reinician y se consumen en orden de compra cuando la cuota mensual se agota.packs.currentes el pack en uso ahora; cada elemento muestra sus propiosusedyremaining. En cuentas sin plan mensual,subscriptioninforma la suma de todos los packs. - Créditos de pago por uso (
credits): se usan solo cuando cuota y packs están agotados. Se facturan aparte.
remaining es el total aún disponible en los tres saldos y total_used el total consumido. Cuando remaining llega a 0, las llamadas devuelven 402 hasta que se añada un pack o créditos.
NotasLink to Notas
- Este endpoint requiere un encabezado
x-api-keyválido. Las solicitudes sin clave devolverán401 Unauthorized. - Los valores
percent_usedpueden superar 100 en escenarios de recarga o exceso. - Los valores
rate_limitsonnullpara planes sin limitación de tasa.
Casos de uso principalesLink to Casos de uso principales
- 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
¿Listo para empezar?
Tu API de web scraping está a un clic. Comienza con +500 créditos, sin infraestructura que configurar, sin proxies que gestionar y sin necesidad de tarjeta de crédito.
- +500 créditos
- Sin tarjeta de crédito
- Todos los endpoints incluidos