---
title: "Start an on-demand backup"
method: POST
path: "/clusters/{cluster_id}/backups"
tags: ["Cluster Backups"]
---

# Start an on-demand backup

`POST /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`

Starts a backup now, kept for `retention_days` (1 to the plan maximum). It is listed with type `manual`.

Returns `409` while another backup of the cluster is queued or running, or while the
cluster is still provisioning, and `402` on plans without managed backups.

Required scope: `clusters:backups:write`

## Path parameters

- `cluster_id` string, uuid, required

## Headers

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

## Request body

- CreateBackupRequest
  - `retention_days` integer, required: Days to keep this backup, from 1 to the plan maximum (Business 14, Enterprise 30).

## Response `202`

The backup was queued. Poll `GET /clusters/{cluster_id}/backups/{backup_id}` until `status` is `completed` or `failed`, or subscribe to the `backup.completed` and `backup.failed` webhooks.

- Backup
  - `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.
- `402`: Client error
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `409`: The request conflicts with the current state of the server.
- `422`: Client error
- `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)