---
title: "List a cluster's backups"
method: GET
path: "/clusters/{cluster_id}/backups"
tags: ["Cluster Backups"]
---

# List a cluster's backups

`GET /clusters/{cluster_id}/backups`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/backups`
- Auth: API key in header `API-Key`

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`

## Path parameters

- `cluster_id` string, uuid, required

## Headers

- `API-Version` '2026-06-01.beta', required

## Response `200`

The request has succeeded.

- BackupList
  - `entitled` boolean, required: Whether the workspace plan includes managed backups (Business and Enterprise).
  - `max_retention_days` integer, required: Retention of automatic backups, and the most days an on-demand backup can be kept. `0` when not entitled.
  - `storage_used_bytes` integer, required: Bytes of this cluster's backups currently stored.
  - `next_scheduled_at` string, date-time: When the next automatic backup starts.
  - `backups` Backup[], required: Backups, newest first.
    - `id` string, required: Backup identifier: `auto-<yyyymmddhhmm>` for an automatic backup, `manual-<timestamp>-<suffix>` for an on-demand one.
    - `cluster_id` string, uuid, required
    - `type` 'automatic' | 'manual', required
    - `status` 'pending' | 'running' | 'completed' | 'failed' | 'deleted', required
    - `retention_days` integer, required: Days the backup is kept after it completes.
    - `size_bytes` integer, required: Size of the stored backup in bytes. Set once `status` is `completed`.
    - `sha256` string: SHA-256 of the stored (encrypted) object, hex. Set once `status` is `completed`.
    - `keycloak_version` string: Keycloak version whose database was backed up.
    - `failure_reason` string: Machine-readable failure cause when `status` is `failed`: `JobFailed`, `JobLost`, `Missed`, `BackupsDisabled`, `InvalidReport`, `DatabaseNotReady` or `StorageNotConfigured`.
    - `requested_at` string, date-time
    - `started_at` string, date-time
    - `completed_at` string, date-time
    - `expires_at` string, date-time: When the backup is deleted from storage.
    - `deleted_at` string, date-time: When the backup was deleted from storage, for `status` `deleted`.
    - `created_at` string, date-time, required

## Other responses

- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)