Backups
Manage a cluster’s managed backups from scripts and CI. Managed backups are available on the Business and Enterprise plans.
Your API key needs clusters:backups:read to read backups and the schedule, and clusters:backups:write to start a backup, change the schedule or download (write includes read).
List backups
curl "https://api.skycloak.io/clusters/$CLUSTER_ID/backups" \
-H "API-Key: $SKYCLOAK_API_KEY" \
-H "API-Version: 2026-06-01.beta"{
"entitled": true,
"max_retention_days": 14,
"storage_used_bytes": 52428800,
"next_scheduled_at": "2026-09-24T03:00:00Z",
"backups": [
{
"id": "auto-202609230300",
"cluster_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "automatic",
"status": "completed",
"retention_days": 14,
"size_bytes": 52428800,
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"requested_at": "2026-09-23T03:00:00Z",
"completed_at": "2026-09-23T03:04:12Z",
"expires_at": "2026-10-07T03:04:12Z",
"created_at": "2026-09-23T03:00:00Z"
}
]
}status is pending, running, completed, failed or deleted (expired). On plans without managed backups the list is empty and entitled is false.
Get a single backup with GET /clusters/{cluster_id}/backups/{backup_id}.
Start a backup
curl -X POST "https://api.skycloak.io/clusters/$CLUSTER_ID/backups" \
-H "API-Key: $SKYCLOAK_API_KEY" \
-H "API-Version: 2026-06-01.beta" \
-H "Content-Type: application/json" \
-d '{"retention_days": 7}'Returns 202 with the queued backup (type manual) and a Location header to poll. retention_days runs from 1 to your plan’s maximum (Business 14, Enterprise 30).
| Status | Meaning |
|---|---|
402 |
Your plan does not include managed backups. |
409 |
Another backup of this cluster is queued or running, or the cluster is still being created. |
422 |
retention_days is outside the allowed range. |
Rather than polling, you can subscribe to the backup.completed and backup.failed webhooks.
Daily backup time
curl "https://api.skycloak.io/clusters/$CLUSTER_ID/backup-schedule" \
-H "API-Key: $SKYCLOAK_API_KEY" \
-H "API-Version: 2026-06-01.beta"{ "time_of_day": "03:00", "source": "maintenance_window", "default_time_of_day": "03:00" }Set your own time (24-hour UTC), or send null to follow the maintenance window again:
curl -X PUT "https://api.skycloak.io/clusters/$CLUSTER_ID/backup-schedule" \
-H "API-Key: $SKYCLOAK_API_KEY" \
-H "API-Version: 2026-06-01.beta" \
-H "Content-Type: application/json" \
-d '{"time_of_day": "02:30"}'Download a backup
Ask for a one-time link, then fetch it. A backup contains every user and their credentials, so include_credentials must be true; it defaults to false and the request is refused with 422 without it.
URL=$(curl -s -X POST "https://api.skycloak.io/clusters/$CLUSTER_ID/backups/auto-202609230300/download-link" \
-H "API-Key: $SKYCLOAK_API_KEY" \
-H "API-Version: 2026-06-01.beta" \
-H "Content-Type: application/json" \
-d '{"include_credentials": true}' | jq -r .url)
curl -fsSL -o backup.dump "$URL"The link works once and expires after about 15 minutes. Only completed backups that have not expired can be downloaded (409 otherwise). The file is a PostgreSQL custom-format archive; restore it with pg_restore. Every download is recorded in your audit log.