> For the complete documentation index, see [llms.txt](https://docs.speedtest-tracker.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.speedtest-tracker.dev/api/responses/speedtests.md).

# Speedtests

Endpoints for running speedtests and listing servers.

## POST /api/v1/speedtests/run

> Run a new Ookla speedtest

```json
{"openapi":"3.0.0","info":{"title":"Speedtest Tracker API","version":"1.0.0"},"tags":[{"name":"Speedtests","description":"Endpoints for running speedtests and listing servers."}],"paths":{"/api/v1/speedtests/run":{"post":{"tags":["Speedtests"],"summary":"Run a new Ookla speedtest","operationId":"runSpeedtest","parameters":[{"$ref":"#/components/parameters/AcceptHeader"},{"name":"server_id","in":"query","description":"Optional Ookla speedtest server ID","required":false,"schema":{"type":"integer"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeedtestRun"}}}},"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":{"SpeedtestRun":{"description":"A queued speedtest result","properties":{"data":{"description":"Queued speedtest result payload","properties":{"id":{"type":"integer"},"service":{"type":"string"},"ping":{"type":"number","format":"float","nullable":true},"download":{"type":"integer","nullable":true},"upload":{"type":"integer","nullable":true},"benchmarks":{"type":"object","nullable":true},"healthy":{"type":"boolean","nullable":true},"status":{"type":"string"},"scheduled":{"type":"boolean"},"comments":{"type":"string","nullable":true},"data":{"description":"Additional data for queued result","properties":{"server":{"properties":{"id":{"type":"integer","nullable":true}},"type":"object"}},"type":"object"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"type":"object","additionalProperties":false},"message":{"description":"Response status message","type":"string"}},"type":"object","additionalProperties":false},"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"}}}}
```

## GET /api/v1/speedtests/list-servers

> List available Ookla speedtest servers

```json
{"openapi":"3.0.0","info":{"title":"Speedtest Tracker API","version":"1.0.0"},"tags":[{"name":"Speedtests","description":"Endpoints for running speedtests and listing servers."}],"paths":{"/api/v1/speedtests/list-servers":{"get":{"tags":["Speedtests"],"summary":"List available Ookla speedtest servers","operationId":"listSpeedtestServers","parameters":[{"$ref":"#/components/parameters/AcceptHeader"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServersCollection"}}}},"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"}}}}}}}},"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":{"ServersCollection":{"description":"Collection of Ookla speedtest servers","properties":{"data":{"description":"List of server objects","type":"array","items":{"properties":{"id":{"type":"string"},"host":{"type":"string"},"name":{"type":"string"},"location":{"type":"string"},"country":{"type":"string"}},"type":"object"}},"message":{"description":"Response status message","type":"string"}},"type":"object","additionalProperties":false},"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"}}}}
```