List runs
Returns run history across all boosts, newest first.
/v1/runs
Requires scope: runs:read
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
boost_id | integer | Optional | Filter by boost ID. |
limit | integer | Optional | Number of results per page. Default: 20, max: 100. |
offset | integer | Optional | Pagination offset. Default: 0. |
Example request
curl "https://api.cache-boost.com/v1/runs?boost_id=15&limit=20" \
-H "Authorization: Bearer cb_live_YOUR_KEY"
Response
Returns 200 OK with a paginated list of run objects.
{
"data": [
{
"id": 88,
"boost_id": 15,
"status": "done",
"status_message": null,
"started_at": "2025-01-15T01:00:05Z",
"finished_at": "2025-01-15T01:04:22Z",
"summary": {
"total_calls": 1240,
"successful_calls": 1238,
"failed_calls": 2,
"cache_hits": 1165,
"average_response_time_ms": 112.5,
"pops": {"CDG": 620, "AMS": 618}
},
"validation": {
"ratio": 10,
"sampled": 11,
"count_hit": 10,
"count_hit_timing": 0,
"count_miss": 1,
"count_pop_mismatch": 0,
"count_error": 0,
"count_unknown": 0,
"avg_first_time": 429,
"avg_check_time": 61,
"causes": {"set-cookie": 1},
"capped": false,
"skipped": null
},
"validation_status": "verified",
"created_at": "2025-01-15T01:00:00Z"
}
],
"limit": 20,
"offset": 0
}
Status values
| Value | Description |
|---|---|
pending | Run is queued and waiting to start. |
running | Run is currently in progress. |
done | Run completed successfully. |
failed | Run ended with errors. |
paused | Run was paused due to high error rate. |
Validation fields
When a post-warm check was requested (validation_ratio above 0), a share of the warmed URLs is requested a second time and compared with the first call. Runs without a check return "validation": null.
| validation_status | Description |
|---|---|
verified | At least 80% of the conclusive checks are cache hits. |
to_fix | Fewer than 80% of the conclusive checks are cache hits. |
probable | The site sends no cache status header (no HIT or MISS read): the check could only compare response times. The rate is then taken over the whole sample. |
not_verified | No conclusive check: validation disabled, run created before the feature, or only inconclusive results. |
in_progress | The run is still running and its checks are pending. Poll again: validation is null until the run ends. |
The rate is (count_hit + count_hit_timing) / (count_hit + count_hit_timing + count_miss). count_pop_mismatch, count_error and count_unknown are inconclusive and left out. When count_hit and count_miss are both 0 (probable), no page can be a miss, so the rate is count_hit_timing / (count_hit_timing + count_unknown). avg_first_time and avg_check_time (ms) are the average response times of the first and second call. causes counts the misses by cause. capped is true when the quota reduced the sample; skipped is "quota" when it cancelled it.
Errors
| Code | Description |
|---|---|
401 | Missing or invalid API key. |
403 | Insufficient scope. |