Update Recovery Point Retention

Product version: 11.2

Last modified: 5 August 2026

Applies one retention policy to a list of existing recovery points in a single call. The supported policies are USE_JOB_RETENTION, KEEP_FOREVER, and PROTECT_UNTIL.

This method requires a user account with the permission to manage Backup Repositories, and it is available only when the HTTP API is enabled for the product instance. Whether the HTTP API can be enabled depends on the license edition. In a multi-tenant deployment, a request cannot change recovery points that belong to another tenant.

Endpoint

https://<Director_IP_address>:4443/c/router

Tenant Endpoint

For tenants of the multi-tenant product the endpoint must be:

https://<Director_IP_address>:4443/t/<tenant_UUID>/c/router

Request Example

The retention period can be set in two ways. The following example sets a relative period, counted from the creation time of each recovery point, so each recovery point gets its own Protect Until date.

curl - relative retention period

Copy

curl --request POST \
    --url https://<Director_IP_address>:4443/c/router \
    --header "content-type: application/json" \
    --cookie @cookies.txt \
    --data '{
    "action": "BackupManagement",
    "method": "updateSavepointsRetention",
    "data": [{
        "savepointIds": [73, 74, 75],
        "protectedPolicy": "PROTECT_UNTIL",
        "keepCount": 3,
        "keepType": "MONTHS"
    }],
    "type": "rpc",
    "tid": 1}'

The following example sets an absolute Protect Until date. The same date is applied to every recovery point in the request, regardless of when each recovery point was created.

curl - absolute Protect Until date

Copy

curl --request POST \
    --url https://<Director_IP_address>:4443/c/router \
    --header "content-type: application/json" \
    --cookie @cookies.txt \
    --data '{
    "action": "BackupManagement",
    "method": "updateSavepointsRetention",
    "data": [{
        "savepointIds": [73, 74, 75],
        "protectedPolicy": "PROTECT_UNTIL",
        "expired": "2027-01-01T00:00:00Z"
    }],
    "type": "rpc",
    "tid": 1}'

Request Fields

Field	Type	Value(s)
`action`	string	`BackupManagement`
`method`	string	`updateSavepointsRetention`
`data`	array	Retention settings to apply to the recovery points
`type`	string	`rpc`
`tid`	int	1

Data

Field	Type	Value(s)
`savepointIds`	array of long	Required. IDs of the recovery points to update. The array must not be empty and can contain up to 10,000 distinct IDs.
`protectedPolicy`	string	Required. Retention policy to apply: `USE_JOB_RETENTION`, `KEEP_FOREVER`, or `PROTECT_UNTIL`.
`expired`	DateTime	Absolute date until which the recovery points are protected, in the ISO-8601 format, for example `2027-01-01T00:00:00Z`. The date and time must be separated by `T`. Applies to `PROTECT_UNTIL` only.
`keepCount`	int	Length of the relative retention period, counted from the creation time of each recovery point. Use together with `keepType`. The supported ranges are 1 to 10,000 for `DAYS`, 1 to 3,000 for `WEEKS`, 1 to 1,200 for `MONTHS`, and 1 to 200 for `YEARS`. Applies to `PROTECT_UNTIL` only.
`keepType`	string	Unit of the relative retention period: `DAYS`, `WEEKS`, `MONTHS`, or `YEARS`. Use together with `keepCount`. Applies to `PROTECT_UNTIL` only.

Notes

For PROTECT_UNTIL, provide exactly one of the following: an absolute expired date, or a relative period defined by keepCount and keepType. A request that contains both or neither is rejected.
Do not send expired, keepCount, or keepType with KEEP_FOREVER or USE_JOB_RETENTION. Such a request is rejected.
The UTC offset in expired is optional but recommended. If the offset is omitted, the date is interpreted in the time zone of the Director, so the same request can refer to different points in time on different Directors. Always send an explicit offset, for example 2027-01-01T00:00:00Z.
USE_JOB_RETENTION is accepted only for recovery points that already follow the job retention. This includes older recovery points that have no stored retention policy but are set to follow the job retention. It is not accepted for any other recovery point, including one that has an explicit PROTECT_UNTIL date or the KEEP_FOREVER policy, and such a recovery point is reported in failures. To recalculate existing recovery points according to the current schedule retention policy, use Recalculate Recovery Point Retention.
If the requested date is earlier than the immutability (object lock) date of a recovery point, that recovery point is reported in failures.
Retention cannot be changed while the Backup Repository that stores the recovery points is detached. Such recovery points are reported in failures until the repository is reattached.
If the call includes a recovery point that cannot be processed, for example a corrupted, missing, or pending-removal recovery point, other recovery points in the same call can also be reported in failures and left unchanged. Repeat the call without the affected recovery points. The method is idempotent, so a repeated call is safe.
A recovery point that is locked by a running job is reported in failures, and its retention is left unchanged.
The background remover that deletes expired recovery points reads the same fields this method writes, so a Protect Until date in the past makes a recovery point eligible for removal in the next cycle. The last uncorrupted recovery point of a backup is never removed, and a recovery point with the KEEP_FOREVER policy is never removed.
Changing the retention of a full recovery point does not affect the restorability of the incremental recovery points that depend on it.

Response Sample

curl

Copy

{
    "action": "BackupManagement",
    "method": "updateSavepointsRetention",
    "tid": "1",
    "type": "rpc",
    "message": null,
    "where": null,
    "cause": null,
    "data": {
        "updatedIds": [73, 75],
        "skippedIds": [],
        "failures": [
            {
                "savepointId": 74,
                "reason": "Update physical savepoint metadata failed: <RESULT>."
            }
        ]
    }
}

Response Fields

Field	Value	Description
`message`	string	Message if the request failed
`where`	string	Reference to the method where the problem occurred
`cause`	string	Cause of failure
`data.updatedIds`	array of long	Recovery points updated successfully. This includes the recovery points that already had the requested retention.
`data.skippedIds`	array of long	Recovery points that were requested but not changed, for example a missing recovery point, one whose removal is pending, or one that was removed after its ID was collected.
`data.failures`	array of object	Recovery points that could not be updated. Each entry has the following format: `{ "savepointId": <long>, "reason": <string> }`

Processing Large Sets

Each call accepts up to 10,000 recovery point IDs.

The retention change is applied synchronously: the call does not return until every recovery point has been written. On a live Backup Repository, each recovery point takes about two seconds to write, so a call that covers thousands of recovery points runs for hours. The HTTP client can reach its own timeout and show no response while the Director continues and completes the change. This is expected for a request of that size and does not mean that the call failed. To confirm the result, read the recovery points again, as described in List all Recovery Points.

To stay within the timeout of the HTTP client, split the IDs into small batches of about 150 recovery points, call the method once per batch, and merge the results. The method is idempotent, so a batch can be retried safely.