Recalculate Recovery Point Retention

Product version: 11.2

Last modified: 5 August 2026

Recalculates the retention of recovery points based on the current schedule retention policy of the backup job that owns them. By default, only the recovery points that follow the job retention are recalculated.

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

Copy 
curl --request POST \
    --url https://<Director_IP_address>:4443/c/router \
    --header "content-type: application/json" \
    --cookie @cookies.txt \
    --data '{
    "action": "BackupManagement",
    "method": "recalculateSavepointsRetention",
    "data": [{
        "backupObjectVids": ["BACKUP_OBJECT-21017"],
        "recomputeExplicitRetention": true
    }],
    "type": "rpc",
    "tid": 1}'

Request Fields

Field

Type

Value(s)

action

string

BackupManagement

method

string

recalculateSavepointsRetention

data

array

Backup objects to process and the recalculation options

type

string

rpc

tid

int

1

Data

Field

Type

Value(s)

backupObjectVids

array of string

Required. Backup objects whose recovery points are recomputed, each in the BACKUP_OBJECT-<id> format. Up to 1,000 backup objects per call.

savepointIds

array of long

Optional. Restricts the change to the listed recovery points, up to 10,000. Listing a recovery point also forces it to be recomputed regardless of its current retention.

recomputeExplicitRetention

boolean

When set to false, which is the default, only the recovery points that currently follow the job retention are recomputed. Recovery points that have an explicit PROTECT_UNTIL date or the KEEP_FOREVER policy are preserved.

Notes

  • By default, only recovery points that follow the job retention are recalculated, so a call can result in no changes when the selected recovery points have explicit retention. Whether a recovery point follows the job retention is determined by its retention policy, not by the presence of a stored Protect Until date: a recovery point that follows the job retention can also have a date, calculated from the job. To recalculate recovery points with an explicit PROTECT_UNTIL date or the KEEP_FOREVER policy, set recomputeExplicitRetention to true or list them in savepointIds.

  • An immutable (object lock) recovery point is left unchanged and reported in skippedIds whenever the recomputed retention would be a Protect Until date, regardless of that date, because the exact immutability floor cannot be established during recalculation.

  • Retention cannot be recomputed 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.

  • To apply a retention policy directly instead of recomputing it from the backup job, use Update Recovery Point Retention.

Retention Calculation

Only the schedule types present on the owning backup job are evaluated: PERIODIC as days, WEEKLY as weeks, MONTHLY as months, and YEARLY as years. RUN_AFTER_JOB and NONE are ignored.

Within each evaluated schedule, the most recent recovery point wins and receives a Protect Until date taken from the keep-for period of that schedule. A recovery point that wins under several schedules receives the longest of those periods. A recovery point that wins none is assigned the KEEP_FOREVER policy.

On incremental-with-full Backup Repositories, the weekly, monthly, and yearly schedules consider full recovery points only, so a schedule with no full recovery point has no winner.

Response Sample

Copy 
{
    "action": "BackupManagement",
    "method": "recalculateSavepointsRetention",
    "tid": "1",
    "type": "rpc",
    "message": null,
    "where": null,
    "cause": null,
    "data": {
        "updatedIds": [201, 202, 203],
        "skippedIds": [204],
        "failures": []
    }
}

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 recomputed and saved successfully.

data.skippedIds

array of long

Recovery points that were requested but not changed, for example a backup object that has no owning schedule retention job or has an ambiguous one, an immutable recovery point whose recomputed retention would be a Protect Until date, 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 recomputed. Each entry has the following format: { "savepointId": <long>, "reason": <string> }

Processing Large Sets

Each call accepts up to 1,000 backup objects and up to 10,000 recovery points.

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, keep each call small: group the backup objects so that each call covers about 150 recovery points, or use savepointIds to limit a single large backup object to about that many recovery points, and repeat the call. The method is idempotent, so a call can be retried safely.