# Stats

Endpoints for retrieving aggregated statistics and performance metrics. Requires `speedtests:read` token scope.

## GET /api/v1/stats

> Fetch aggregated Speedtest statistics

```json
{"openapi":"3.0.0","info":{"title":"Speedtest Tracker API","version":"1.0.0"},"tags":[{"name":"Stats","description":"Endpoints for retrieving aggregated statistics and performance metrics. Requires `speedtests:read` token scope."}],"paths":{"/api/v1/stats":{"get":{"tags":["Stats"],"summary":"Fetch aggregated Speedtest statistics","operationId":"getStats","parameters":[{"$ref":"#/components/parameters/AcceptHeader"},{"name":"start_at","in":"query","description":"Filter stats from this date/time (ISO 8601)","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"end_at","in":"query","description":"Filter stats up to this date/time (ISO 8601)","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Statistics fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}},"401":{"description":"Unauthenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedError"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenError"}}}},"406":{"description":"Not Acceptable - Missing or invalid Accept header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotAcceptableError"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}}},"components":{"parameters":{"AcceptHeader":{"name":"Accept","in":"header","description":"Must be \"application/json\" - this API only accepts and returns JSON","required":true,"schema":{"type":"string","default":"application/json"}}},"schemas":{"Stats":{"description":"Aggregated speedtest statistics","properties":{"total_results":{"type":"integer"},"avg_ping":{"type":"number","format":"float"},"avg_download":{"type":"number","format":"float"},"avg_upload":{"type":"number","format":"float"},"min_ping":{"type":"number","format":"float"},"min_download":{"type":"number","format":"float"},"min_upload":{"type":"number","format":"float"},"max_ping":{"type":"number","format":"float"},"max_download":{"type":"number","format":"float"},"max_upload":{"type":"number","format":"float"}},"type":"object"},"UnauthenticatedError":{"description":"Error when user is not authenticated","properties":{"message":{"description":"Unauthenticated error message","type":"string"}},"type":"object"},"ForbiddenError":{"description":"Forbidden error response when user lacks permission","properties":{"message":{"description":"Error message indicating lack of permission","type":"string"}},"type":"object"},"NotAcceptableError":{"description":"Error response when the Accept header is missing or invalid","properties":{"message":{"type":"string"},"error":{"type":"string"}},"type":"object"},"ValidationError":{"description":"Validation failed due to invalid server_id input","properties":{"message":{"description":"Validation failed due to invalid server_id input","type":"string"}},"type":"object"}}}}
```