Skip to main content
Network status
Log in
Piloterr
Back to library

Stats API

Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.

ActiveFreeGET/v2/stats
Try endpoint for freePiloterr

Endpoint Overview

Detailed documentation, pricing, and usage examples.

OverviewLink to Overview

The Stats endpoint returns a single infrastructure health snapshot for an API engine or a specific path. Metrics are aggregated across the whole platform over a one-hour window. They are not your account or tenant usage. There is no hourly time series. Use the Usage endpoint for your Piloterr account quota.

This endpoint is free. It never consumes any credits.

API Stats is enabled per account. HTTP 403 means it is not active on your account. Contact support to activate it.

QuickstartLink to Quickstart

GET https://api.piloterr.com/v2/stats?engine=website

GET https://api.piloterr.com/v2/stats?path=/v2/website/crawler

Authentication uses the x-api-key header.

ParametersLink to Parameters

Provide at least one of engine or path.

Parameter Type Required Description
engine string no API family to check, for example website.
path string no Specific endpoint to check, for example /v2/website/crawler. If you also pass engine, use an endpoint from that API.
x-api-key string yes Your private Piloterr API key

Health valuesLink to Health values

  • operational: success rate at or above 99%
  • degraded: success rate from 90% up to 99%
  • down: success rate below 90%

Response fieldsLink to Response fields

Field Type Description
engine string Engine slug derived from the catalog (for example website)
path string | null Normalized path filter, or null when you query by engine only
health string operational, degraded, or down for the last hour
success_rate number Success rate over the last hour. Only HTTP 5xx counts as failure. Low-volume windows are smoothed.
avg_response_time_ms integer Average response time in milliseconds. Durations above 60 seconds are excluded.
window string Aggregation window. Always 1h.

The response does not include request volume or raw error counts.

ErrorsLink to Errors

Code Description
400 Missing engine and path, invalid value, or path that does not match engine
401 Missing or invalid API key
403 API Stats is not enabled for this account. Contact support to activate it.
404 Unknown engine (not in the API catalog)
503 Status data is temporarily unavailable

NotesLink to Notes

  • These are infrastructure stats for the platform, not stats for your account or tenant. Every authenticated caller sees the same health snapshot.
  • API Stats is enabled per account. HTTP 403 means it is not active on your account. Contact support to activate it.
  • Provide at least engine or path. Requests with neither return 400.
  • Use Usage (/v2/usage) for your remaining credits and rate limits.

Main use casesLink to Main use cases

  • Gate batch jobs when an engine is degraded or down
  • Show a live health badge next to a specific endpoint
  • Alert when success_rate drops below your own threshold

Ready to get started?

Your web scraping API is one click away. Start with +500 credits, no infrastructure to set up, no proxies to manage, and no credit card required.

  • +500 credits
  • No credit card required
  • All endpoints included
Start free (+500 credits)PiloterrTalk to a data expert