Drill status API
Each project can have a public, read-only link that returns the result of its latest restore drill as JSON: passed or not, when it finished and how long the restore took. Use it for a status page, a monitoring script or a README badge. It’s off until you turn it on, and it never shows anything else about the project.
curl "https://app.backupdrill.com/api/v1/drill-status/<token>"{
"result": "passed",
"finishedAt": "2026-10-24T03:12:00.000Z",
"restoreSeconds": 42
}Turn it on
- Open the project in the console.
- Under Restore drills, click Turn on public drill status.
- Copy the link that appears. The last part of it is the token.
Turning it off makes the link return 404 within a few minutes. Turning it on again gives a new token, so an old link never comes back to life.
Request
GET https://app.backupdrill.com/api/v1/drill-status/<token>
No API key or sign-in. The token is a random 22-character string (base64url) and is the only thing that identifies the project. Responses carry Access-Control-Allow-Origin: *, so a browser page on any domain can fetch it.
Response
| Field | Type | Meaning |
|---|---|---|
result | string | One of passed, failed, error or none. See the table below. |
finishedAt | string or null | When the latest finished drill ended, in UTC (ISO 8601). Null when result is none. |
restoreSeconds | number or null | How long pg_restore took, rounded to whole seconds. Null when result is error or none. |
| result | Meaning |
|---|---|
passed | The snapshot restored into a throwaway Postgres and every check passed. |
failed | The drill ran to the end, but the restore or one of its checks failed. The drill report in the console says which. |
error | The drill couldn't finish, for example because the bucket rejected the key. Nothing was verified either way. |
none | No drill has finished for this project yet. |
Only finished drills count. A drill that is queued or still running doesn’t change the response until it ends. A project with no finished drill yet returns:
{
"result": "none",
"finishedAt": null,
"restoreSeconds": null
}Drills run weekly on paid plans. On the Free plan a project gets one drill after its first backup, so its result stays the same after that and finishedAt keeps getting older.
Status codes
| Status | Meaning |
|---|---|
| 200 | The body above. |
| 404 | The token doesn't exist, has the wrong format, or the owner turned public drill status off. |
| 503 | We couldn't read the result just now. Try again later. |
Error bodies are JSON with a single error field, for example {"error": "not found"}.
Caching and how often to call it
Successful responses are cached for 5 minutes and 404s for 1 minute, so calling more often than that returns the same answer. There is no per-client limit today. Please keep automated checks to about once every 5 minutes per link. Drills are scheduled weekly, so the result rarely changes within a day.
What the link reveals
Exactly the three fields above. Not the project name, schedule, database, bucket, snapshot sizes or the drill report. Anyone with the link can read your drill results, including anyone who finds it in a public README. That’s the point of it, so only turn it on for projects you’re happy to show.