# Stats

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/stats` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 0 credits per call |
| **Documentation** | https://www.piloterr.com/library/stats |

## Description

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.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/stats' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Engine health snapshot

```json
{
  "path": null,
  "engine": "website",
  "health": "operational",
  "window": "1h",
  "success_rate": 99.412,
  "avg_response_time_ms": 840
}
```

### Path health snapshot

```json
{
  "path": "/v2/website/crawler",
  "engine": "website",
  "health": "operational",
  "window": "1h",
  "success_rate": 99.412,
  "avg_response_time_ms": 840
}
```

## Documentation

## 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](https://www.piloterr.com/library/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.

## 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.

## 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 values
- `operational`: success rate at or above 99%
- `degraded`: success rate from 90% up to 99%
- `down`: success rate below 90%

## 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.

## 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 |

## 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](https://www.piloterr.com/library/usage) (`/v2/usage`) for your remaining credits and rate limits.

## 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