v1

Authorization

A "Bearer Token" is required to authenticate into the API, you can generate tokens for your user account on /admin/api-tokens.

---

Get result

curl localhost/api/v1/results/{id}
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

Parameters

• id- record ID of the result to get

Responses

• 200: OK

• 404: Result not found

---

List results

curl localhost/api/v1/results
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere

Filtering

You can filter the results response by the fields: ping, download, upload, healthy, status, scheduled and created_at. To filter on created_at use start_atand `end_at`.

Example: filter dates in a range

curl localhost/api/v1/results?filter[start_at]>=2024-01-01&filter[end_at]<=2024-12-31
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

Example: filter for only unhealthy results

curl localhost/api/v1/results?filter[healthy]=false
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

Example: filter for "failed" and "skipped" results

curl localhost/api/v1/results?filter[status]=failed,skipped
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

Sorting

You can sort the results response by the fields: ping, download, upload, created_at or updated_at. Sorting is ascending by default and can be reversed by adding a hyphen (-) to the start of the property name.

curl localhost/api/v1/results?sort=-created_at
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

Responses

• 200: OK

• 422: Unprocessable Entity (validation probably failed, see logs)

---

Get latest result

curl localhost/api/v1/results/latest
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

Responses

• 200: OK

• 404: No result found

---

Stats

curl localhost/api/v1/stats
   -H "Accept: application/json"
   -H "Authorization: Bearer yourtokengoeshere"

Responses

• 200: OK

---

Data Dictionary

The data structure returned mimic the results table but includes the addition of download_bits, upload_bits, download_bits_human and upload_bits_human.

{
  "data": {
    "id": 1009,
    "service": "ookla",
    "ping": 7.448,
    "download": 167270969,
    "upload": 115884569,
    "download_bits": 1338167752,
    "upload_bits": 927076552,
    "download_bits_human": "1.34 Gbps",
    "upload_bits_human": "927.08 Mbps",
    "benchmarks": null,
    "healthy": null,
    "status": "completed",
    "scheduled": true,
    "comments": null,
    "data": {
    },
    "created_at": "2025-01-13 16:37:00",
    "updated_at": "2025-01-13 16:37:17"
  }
}

---

FAQ

Can I create, update or delete results through the API?

No, not at this time its read-only.