List warm runs
Returns on-demand warm run history for a site, newest first.
/v1/sites/{id}/warm-runs
Requires scope: boosts:read
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id |
integer | Required | Site ID. |
Query parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Number of results to return. Default: 20, max: 100. |
offset | integer | Pagination offset. Default: 0. |
Example request
curl https://api.cache-boost.com/v1/sites/42/warm-runs \
-H "Authorization: Bearer cb_live_YOUR_KEY"
Response
Returns 200 OK.
{
"data": [
{
"id": 91,
"status": "done",
"status_message": null,
"source_urls": ["https://www.example.com/", "https://www.example.com/about"],
"run_region": ["fr", "us"],
"started_at": "2025-01-15T10:31:00Z",
"finished_at": "2025-01-15T10:31:45Z",
"summary": {
"total_calls": 4,
"successful_calls": 4,
"failed_calls": 0,
"cache_hits": 3,
"average_response_time_ms": 98.2,
"pops": { "CDG": 2, "IAD": 2 }
},
"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-15T10:30:58Z"
}
],
"total": 1,
"limit": 20,
"offset": 0
}
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 or access denied. |
404 | Site not found. |