Version: 8.9 (unreleased)

Zeebe backup management API

breaking changes

As of the Camunda 8.8 release, the /actuator endpoints for backups have been moved to /actuator/backupRuntime. The previous /actuator/backups endpoint is still active only if the applications are deployed standalone (each application is running in its own process).

Back up a running Zeebe cluster using the Backup Management API.

About this API

A backup of a Zeebe cluster is comprised of a consistent snapshot of all partitions. The backup is taken asynchronously in the background while Zeebe is processing. Thus, the backups can be taken with minimal impact on typical processing. The backups can be used to restore a cluster in case of failures that lead to full data loss or data corruption.

Zeebe provides a REST API to create backups, query, and manage existing backups. The backup management API is a custom endpoint backups, available via Spring Boot Actuator. This is accessible via the management port of the gateway. The API documentation is also available as OpenApi specification.

warning

Usage of this API requires the backup store to be configured for the component.

Zeebe configuration

To use the backup feature in Zeebe, you must choose which external storage system you will use. Make sure to set the same configuration on all brokers in your cluster.

Zeebe supports S3, Google Cloud Storage (GCS), and Azure, and local filesystem for external storage.

caution

Backups created with one store are not available or restorable from another store.

This is especially relevant if you were using GCS through the S3 compatibility mode and want to switch to the new built-in support for GCS now. Even when the underlying storage bucket is the same, backups from one are not compatible with the other.

Create backup API

The following request can be used to start a backup.

Request

POST actuator/backupRuntime
{
  "backupId": <backupId>
}

A backupId is an integer and must be greater than the ID of previous backups that are completed, failed, or deleted. Zeebe does not take two backups with the same ids. If a backup fails, a new backupId must be provided to trigger a new backup. The backupId cannot be reused, even if the backup corresponding to the backup ID is deleted.

note

When either of continuous backups, backup scheduler, or checkpoint scheduler are enabled, the backupId parameter must be omitted. Instead, the ID is generated by the cluster.

Example request

curl --request POST 'http://localhost:9600/actuator/backupRuntime' \
-H 'Content-Type: application/json' \
-d '{ "backupId": "100" }'

Response

Code	Description
202 Accepted	A Backup has been successfully scheduled. To determine if the backup process was completed, refer to the GET API.
400 Bad Request	Indicates issues with the request, for example when the `backupId` is not valid or backup is not enabled on the cluster.
409 Conflict	Indicates a backup with the same `backupId` or a higher ID already exists.
500 Server Error	All other errors. Refer to the returned error message for more details.
502 Bad Gateway	Zeebe has encountered issues while communicating to different brokers.
504 Timeout	Zeebe failed to process the request within a pre-determined timeout.

Example response body with 202 Accepted

{
  "backupId": 1772011199310,
  "message": "A backup with id 100 has been scheduled. Use GET actuator/backups/100 to monitor the status."
}

Get backup info API

Information about a specific backup can be retrieved using the following request:

Request

GET actuator/backupRuntime/{backupId}

Example request

curl --request GET 'http://localhost:9600/actuator/backupRuntime/100'

Response

Code	Description
200 OK	Backup state could be determined and is returned in the response body (see example below).
400 Bad Request	There is an issue with the request. Refer to the returned error message for details.
404 Not Found	A backup with that ID does not exist.
500 Server Error	All other errors. Refer to the returned error message for more details.
502 Bad Gateway	Zeebe has encountered issues while communicating to different brokers.
504 Timeout	Zeebe failed to process the request within a pre-determined timeout.

When the response is 200 OK, the response body consists of a JSON object describing the state of the backup.

backupId: ID in the request.
state: Gives the overall status of the backup. The state can be one of the following:
- COMPLETED if all partitions have completed the backup.
- FAILED if at least one partition has failed. In this case, failureReason contains a string describing the reason for failure.
- INCOMPLETE if at least one partition's backup does not exist.
- IN_PROGRESS if at least one partition's backup is in progress.
- DELETED if at least one partition's backup is deleted.
details: Gives the state of each partition's backup.
failureReason: The reason for failure if the state is FAILED.

Example response body with 200 OK

{
  "backupId": 100,
  "details": [
    {
      "brokerVersion": "8.2.0-SNAPSHOT",
      "checkpointPosition": 5,
      "createdAt": "2022-12-08T13:00:55.344276672Z",
      "lastUpdatedAt": "2022-12-08T13:00:55.805351556Z",
      "partitionId": 1,
      "snapshotId": "2-1-3-2",
      "state": "COMPLETED"
    },
    {
      "brokerVersion": "8.2.0-SNAPSHOT",
      "checkpointPosition": 7,
      "createdAt": "2022-12-08T13:00:55.370965069Z",
      "lastUpdatedAt": "2022-12-08T13:00:55.84756566Z",
      "partitionId": 2,
      "snapshotId": "3-1-5-3",
      "state": "COMPLETED"
    }
  ],
  "state": "COMPLETED"
}

List backups API

Information about all backups can be retrieved using the following request:

Request to list all backups

GET actuator/backupRuntime

Example request

curl --request GET 'http://localhost:9600/actuator/backupRuntime'

Request to list backups matching a prefix

The list of backups can be filtered by specifying a backup ID prefix:

GET actuator/backupRuntime/{backupIdPrefix}

The backup ID prefix must end with *, for example 10* will match all backups with IDs starting with 10.

Example request

curl --request GET 'http://localhost:9600/actuator/backupRuntime/10*'

Response

Code	Description
200 OK	Backup state could be determined and is returned in the response body (see example below).
400 Bad Request	There is an issue with the request. Refer to returned error message for details.
500 Server Error	All other errors. Refer to the returned error message for more details.
502 Bad Gateway	Zeebe has encountered issues while communicating to different brokers.
504 Timeout	Zeebe failed to process the request with in a pre-determined timeout.

When the response is 200 OK, the response body consists of a JSON object with a list of backup info. See get backup info API response for the description of each field.

Example response body with 200 OK

[
  {
    "backupId": 100,
    "details": [
      {
        "brokerVersion": "8.2.0-SNAPSHOT",
        "createdAt": "2022-12-08T13:00:55.344276672Z",
        "partitionId": 1,
        "state": "COMPLETED"
      },
      {
        "brokerVersion": "8.2.0-SNAPSHOT",
        "createdAt": "2022-12-08T13:00:55.370965069Z",
        "partitionId": 2,
        "state": "COMPLETED"
      }
    ],
    "state": "COMPLETED"
  },
  {
    "backupId": 200,
    "details": [
      {
        "brokerVersion": "8.2.0-SNAPSHOT",
        "createdAt": "2022-12-08T13:01:15.27750375Z",
        "partitionId": 1,
        "state": "COMPLETED"
      },
      {
        "brokerVersion": "8.2.0-SNAPSHOT",
        "createdAt": "2022-12-08T13:01:15.279995106Z",
        "partitionId": 2,
        "state": "COMPLETED"
      }
    ],
    "state": "COMPLETED"
  }
]

Delete backup API

A backup can be deleted using the following request:

Request

DELETE actuator/backupRuntime/{backupId}

Example request

curl --request DELETE 'http://localhost:9600/actuator/backupRuntime/100'

Response

Code	Description
204 No Content	The backup has been deleted.
400 Bad Request	There is an issue with the request. Refer to returned error message for details.
500 Server Error	All other errors. Refer to the returned error message for more details.
502 Bad Gateway	Zeebe has encountered issues while communicating to different brokers.
504 Timeout	Zeebe failed to process the request with in a pre-determined timeout.

Request runtime state

Acquire information regarding backups from the runtime state.

Request

GET actuator/backupRuntime/state

Example request

curl --request GET 'http://localhost:9600/actuator/backupRuntime/state'

Response

This endpoint returns the current runtime state of backups and checkpoints across all partitions.

HTTP status codes

Code	Description
200 OK	The backup state was successfully determined and is returned in the response body.
400 Bad Request	The request is invalid. Refer to the returned error message for details.
500 Internal Server Error	An unexpected error occurred while processing the request. Refer to the returned error message for details.
502 Bad Gateway	Zeebe encountered issues while communicating with other brokers.
504 Gateway Timeout	Zeebe was unable to process the request within the configured timeout.

Response body

When the response status is 200 OK, the response body contains a JSON object describing the current backup and checkpoint state.

`checkpointStates`

Latest checkpoint information per partition.

checkpointId: Identifier of the checkpoint.
partitionId: Identifier of the partition.
checkpointType: Type of the checkpoint. One of MARKER, SCHEDULED_BACKUP, or MANUAL_BACKUP.
checkpointPosition: Log stream position of the checkpoint record.
checkpointTimestamp: Timestamp when the checkpoint was created.

`backupStates`

Latest backup information per partition.

checkpointId: Identifier of the associated checkpoint.
partitionId: Identifier of the partition.
checkpointType: Type of the checkpoint. One of MARKER, SCHEDULED_BACKUP, or MANUAL_BACKUP.
checkpointPosition: Log stream position of the checkpoint record.
checkpointTimestamp: Timestamp when the checkpoint was created.
firstLogPosition: First available log stream position included in this backup.

`ranges`

List of active continuous backup ranges per partition.

partitionId: Identifier of the partition.
start: First backup in the continuous backup range.
- checkpointId: Identifier of the checkpoint.
- checkpointType: Type of the checkpoint.
- checkpointPosition: Log stream position of the checkpoint record.
- checkpointTimestamp: Timestamp when the checkpoint was created.
- firstLogPosition: First available log stream position included in this backup.
end: Last backup in the continuous backup range.
- checkpointId: Identifier of the checkpoint.
- checkpointType: Type of the checkpoint.
- checkpointPosition: Log stream position of the checkpoint record.
- checkpointTimestamp: Timestamp when the checkpoint was created.
- firstLogPosition: First available log stream position included in this backup.

Example response body with 200 OK

{
  "checkpointStates": [
    {
      "checkpointId": 1772001869309,
      "checkpointType": "SCHEDULED_BACKUP",
      "partitionId": 1,
      "checkpointPosition": 580,
      "checkpointTimestamp": "2026-02-25T06:44:29.309Z"
    },
    {
      "checkpointId": 1772001869309,
      "checkpointType": "SCHEDULED_BACKUP",
      "partitionId": 2,
      "checkpointPosition": 135,
      "checkpointTimestamp": "2026-02-25T06:44:29.308Z"
    }
  ],
  "backupStates": [
    {
      "checkpointId": 1772001869309,
      "checkpointType": "SCHEDULED_BACKUP",
      "partitionId": 1,
      "checkpointPosition": 580,
      "firstLogPosition": 1,
      "checkpointTimestamp": "2026-02-25T06:44:29.391Z"
    },
    {
      "checkpointId": 1772001869309,
      "checkpointType": "SCHEDULED_BACKUP",
      "partitionId": 2,
      "checkpointPosition": 135,
      "firstLogPosition": 1,
      "checkpointTimestamp": "2026-02-25T06:44:29.394Z"
    }
  ],
  "ranges": [
    {
      "partitionId": 1,
      "start": {
        "checkpointId": 1772001838336,
        "checkpointType": "SCHEDULED_BACKUP",
        "checkpointPosition": 580,
        "firstLogPosition": 1,
        "checkpointTimestamp": "2026-02-25T06:44:29.391Z"
      },
      "end": {
        "checkpointId": 1772001869309,
        "checkpointType": "SCHEDULED_BACKUP",
        "checkpointPosition": 580,
        "firstLogPosition": 1,
        "checkpointTimestamp": "2026-02-25T06:44:29.391Z"
      }
    },
    {
      "partitionId": 2,
      "start": {
        "checkpointId": 1772001838336,
        "checkpointType": "SCHEDULED_BACKUP",
        "checkpointPosition": 135,
        "firstLogPosition": 1,
        "checkpointTimestamp": "2026-02-25T06:44:29.394Z"
      },
      "end": {
        "checkpointId": 1772001869309,
        "checkpointType": "SCHEDULED_BACKUP",
        "checkpointPosition": 135,
        "firstLogPosition": 1,
        "checkpointTimestamp": "2026-02-25T06:44:29.394Z"
      }
    }
  ]
}

About this API​

Create backup API​

Request​

Response​

Get backup info API​

Request​

Response​

List backups API​

Request to list all backups​

Request to list backups matching a prefix​

Response​

Delete backup API​

Request​

Response​

Request runtime state​

Request​

Response​

HTTP status codes​

Response body​

checkpointStates​

backupStates​

ranges​

About this API

Create backup API

Request

Response

Get backup info API

Request

Response

List backups API

Request to list all backups

Request to list backups matching a prefix

Response

Delete backup API

Request

Response

Request runtime state

Request

Response

HTTP status codes

Response body

`checkpointStates`

`backupStates`

`ranges`