---
title: Retain a Backup
description: The Backup Service REST API supports the configuration of retention
  settings for backups in a specified, active repository.
pubDate: 2026-08-17T09:53:44.266Z
antora:
  editUrl: https://github.com/couchbase/docs-server/edit/release/8.0/modules/rest-api/pages/backup-retention.adoc
  xref: xref:server:rest-api:backup-retention.adoc[]
---

[Consult the llms.txt file for a full list of contents](/llms.txt)
[View original HTML](/server/current/rest-api/backup-retention.html)

# Retain a Backup

> The Backup Service REST API supports the configuration of retention settings for backups in a specified, active repository. 

## [](#http-methods-and-uris)HTTP Methods and URIs

Configure retention settings for a repository:

POST /cluster/<cluster-name>/repository/active/<repository-id>/retentionSettings

Configure retention settings for a specific backup in a repository:

POST /cluster/<cluster-name>/repository/active/<repository-id>/retentionSettings/<backup-name>

## [](#description)Description

Configure the Backup Service to retain backups in a repository by setting a retention period. When the retention period is reached, the Backup Service automatically deletes the backup through Prune tasks.

You can set a retention period for a repository when creating it or editing it later. After creating a repository, you can set a custom retention period for its individual backups.

## [](#curl-syntax)Curl Syntax

To set a retention period for a repository, use the following syntax:

curl -X POST <backup-node-ip-address-or-domain-name>:8097/cluster/self/repository/active/<repository-id>/retentionSettings
  -u <username>:<password>
  -d '{"period": <integer between 0 and 36500 inclusive>, "retroactive": <true|false>}'

The `username` and `password` must identify an administrator with the Full Admin role. The `repository-id` argument must specify the name of an active repository defined on the cluster.

`period` indicates a retention period value between 0 and 36500 (inclusive), in days, for the repository. This retention period is applied to all backups in the repository. 0 indicates an indefinite retention period.

`retroactive` is a boolean value that indicates whether the retention period must be applied retroactively to existing backups in the repository.

* If `retroactive` is set to `true`, the new retention period is applied retroactively to all the backups in the repository.
* If `retroactive` is set to `false`, the new retention period is applied only to the new backups created in the repository.

To set a retention period for a specific backup in a repository, use the following syntax:

curl -X POST <backup-node-ip-address-or-domain-name>:8097/cluster/self/repository/active/<repository-id>/retentionSettings/<backup-name>
  -u <username>:<password>
  -d '{"period": <integer between 0 and 36500 inclusive>,}'

The `backup-name` argument must specify the name of a backup within the specified repository, for which retention settings are being configured.

The `period` argument must specify a retention period value between 0 and 36500 (inclusive), in days. This retention period is applied to the specified backup. 0 indicates an indefinite retention period.

## [](#responses)Responses

| Value                                                                   | Description                                                            |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| 200 OK and JSON array containing the expired backups and their details. | Successful call.                                                       |
| 400                                                                     | Invalid parameter.                                                     |
| 400 Object Not found                                                    | The repository in the endpoint URI does not exist.                     |
| 401 Unauthorized                                                        | Authorization failure due to incorrect username or password.           |
| 403 Forbidden, plus a JSON message explaining the minimum permissions.  | The provided username has insufficient privileges to call this method. |
| 404 Object Not Found                                                    | Error in the URI path.                                                 |
| 500 Internal Server Error                                               | Error in Couchbase Server.                                             |

## [](#examples)Examples

The following call sets a retention period for a repository named `repoForRetention` to 30 days, retroactively applied to existing backups:

curl -X POST <backup-node-ip-address-or-domain-name>:8097/cluster/self/repository/active/repoForRetention/retentionSettings
  -u <username>:<password>
  -d '{"period": 30, "retroactive": true}'

If successful, the call returns `200 OK`, and the retention settings are applied to the specified repository.

The following call sets a retention period for a specific backup named `backupOne` in the repository `repoForRetention` to 15 days:

curl -X POST <backup-node-ip-address-or-domain-name>:8097/cluster/self/repository/active/repoForRetention/retentionSettings/backupOne
  -u <username>:<password>
  -d '{"period": 15}'

If successful, the call returns `200 OK`, and the retention settings are applied to the specified backup.

## [](#see-also)See Also

* For setting a retention period for a backup from the UI, see [Set Retention Period for a Specific Backup](../manage/manage-backup-and-restore/manage-backup-and-restore.md#set-retention-period-for-a-backup).
* For setting a retention period for a repository from the UI, see [Set Retention Period after Creating a Repository](../manage/manage-backup-and-restore/manage-backup-and-restore.md#set-retention-period-after-repo-creation).
* For more information on retention settings in the Backup Service, see [Retain Backups](../manage/manage-backup-and-restore/manage-backup-and-restore.md#backup-retention).
* For information about pruning backups, see [Schedule Pruning](../manage/manage-backup-and-restore/manage-backup-and-restore.md#schedule-backup-pruning).
* For more information on the Backup Service, see [Backup Service](../learn/services-and-indexes/services/backup-service.md).