List a cluster's backups
const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/backups';
const options = {
method: 'GET',
headers: {'API-Version': '2026-06-01.beta', 'API-Key': '<API-Key>'}
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}curl --request GET \
--url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/backups \
--header 'API-Key: <API-Key>' \
--header 'API-Version: 2026-06-01.beta'Returns the cluster’s managed backups, newest first, with the storage they use.
On plans without managed backups the list is empty and entitled is false.
Required scope: clusters:backups:read
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Responses
Section titled “Responses”The request has succeeded.
object
Whether the workspace plan includes managed backups (Business and Enterprise).
Retention of automatic backups, and the most days an on-demand backup can be kept. 0 when not entitled.
Bytes of this cluster’s backups currently stored.
When the next automatic backup starts.
Backups, newest first.
object
Backup identifier: auto-<yyyymmddhhmm> for an automatic backup, manual-<timestamp>-<suffix> for an on-demand one.
Days the backup is kept after it completes.
Size of the stored backup in bytes. Set once status is completed.
SHA-256 of the stored (encrypted) object, hex. Set once status is completed.
Keycloak version whose database was backed up.
Machine-readable failure cause when status is failed: JobFailed, JobLost, Missed, BackupsDisabled, InvalidReport, DatabaseNotReady or StorageNotConfigured.
State of the off-site copy to your own bucket. A failed copy never changes status, retention or the download link.
Short failure code when copy_status is failed.
When the copy to your bucket finished, for copy_status copied.
When the backup is deleted from storage.
When the backup was deleted from storage, for status deleted.
The off-site copy destination, when one is set. Never includes the secret.
object
S3-compatible endpoint, for example https://<account>.r2.cloudflarestorage.com. Omitted for AWS S3.
Signing region. Required with a custom endpoint.
Key prefix the copies are written under: <prefix>/<cluster_id>/<backup_id>.dump and .json.
Whether finished backups are copied. Turn off to pause copying without removing the destination.
When Test connection last ran against this destination.
Whether the last Test connection succeeded.
The provider’s error from the last failed Test connection.
Example
{
"backups": [
{
"id": "auto-202609230300",
"cluster_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "automatic",
"status": "completed",
"retention_days": 14,
"size_bytes": 52428800,
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"keycloak_version": "26.3.0",
"copy_status": "copied",
"copied_at": "2026-09-23T03:09:30Z",
"requested_at": "2026-09-23T03:00:00Z",
"started_at": "2026-09-23T03:00:04Z",
"completed_at": "2026-09-23T03:04:12Z",
"expires_at": "2026-10-07T03:04:12Z",
"created_at": "2026-09-23T03:00:00Z"
}
],
"destination": {
"bucket": "acme-keycloak-backups",
"region": "eu-central-1",
"prefix": "skycloak",
"access_key_id": "AKIAEXAMPLE",
"enabled": true,
"created_at": "2026-11-08T10:00:00Z",
"updated_at": "2026-11-08T10:00:00Z"
}
}Access is unauthorized.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Access is forbidden.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}The server cannot find the requested resource.
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Client error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Headers
Section titled “Headers”Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}Server error
RFC 9457 Problem Details object.
object
Example generated
{
"type": "https://example.com",
"title": "example",
"status": 1,
"detail": "example",
"instance": "https://example.com"
}