---
title: "Restore data with Aerospike Backup Service"
description: "Restore Aerospike Database data from Aerospike Backup Service (ABS) backups by timestamp or by backup path."
---

# Restore data with Aerospike Backup Service

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

Aerospike Backup Service (ABS) restores data asynchronously. A restore request returns a job ID. Poll that ID until the job reaches a terminal status.

For how full and incremental backups form a chain, see [Concepts](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts). For request bodies, see [API usage examples](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/api-examples).

## Applies to

-   Product: Aerospike Backup Service (ABS) 3.7.x.
-   Audience: database administrators and operators who restore data after data loss, for disaster recovery, or into another cluster.
-   Outcome: `GET /v1/restore/status/JOB_ID` reports `success`, and the record counters (`read-records`, `inserted-records`, `fresher-records`) match what you expected to restore.

Set `BASE_URL` to your ABS listen address:

Terminal

```bash
export BASE_URL=http://localhost:8080
```

## Before you start

-   ABS is installed and can reach the destination Aerospike Database cluster. See [Install Aerospike Backup Service](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install).
-   The backup chain is in the storage that ABS reads: a full backup, plus any incremental backups up to the restore time. `GET /v1/backups/full` and `GET /v1/backups/incremental` list what exists.
-   The Database user on the destination cluster has `read-write` to restore records. Restoring UDFs requires `udf-admin` (Database 6.0.0 and later) or `data-admin`. Restoring secondary indexes and set indexes requires `sindex-admin` (Database 6.0.0 and later) or `data-admin`. See [Privileges](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts#privileges).

## Choose a restore method

| Method | Endpoint | Use when |
| --- | --- | --- |
| Timestamp | `POST /v1/restore/timestamp` | You want the cluster at a point in time. With `incr-mode: differential` (default), ABS restores the last full backup before `time`, then every incremental up to `time`. With `incr-mode: cumulative`, ABS restores that full backup plus the latest covering incremental. |
| Path | `POST /v1/restore/full` | You want one backup directory. You pass storage plus `backup-data-path` (the `key` from `GET /v1/backups/full`). The path is relative to the storage `path` and must be clean (no `..`). |

Timestamp restore is the usual disaster-recovery path. Path restore is useful when you already identified a backup directory, or when you restore onto a cluster that does not define the original routine.

## Restore by timestamp

`time` is Unix time in milliseconds (an absolute instant). [`schedule-timezone`](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure#quartz-schedules) does not change how it is interpreted. ABS restores the closest backup state before that time. The backup timestamp is the time the job started, not the time it finished.

Standard restore using a routine that exists in the local configuration:

```json
{

  "routine": "app-daily",

  "time": 1739538000000

}
```

Terminal window

```shell
curl -s -X POST "$BASE_URL/v1/restore/timestamp" \

  -H "Content-Type: application/json" \

  -d '{"routine":"app-daily","time":1739538000000}'
```

The response is a numeric job ID.

### Optional overrides (ABS 3.6.0 and later)

You can override storage, destination cluster, and Secret Agent in the request body. If you omit an override, ABS uses the matching field from the local routine.

| Override | Fields | Notes |
| --- | --- | --- |
| Storage | `source` or `source-name` | Mutually exclusive. |
| Destination | `destination` or `destination-name` | Mutually exclusive. |
| Secret Agent | `secret-agent` or `secret-agent-name` | Decrypts backup files. Destination credentials can include an inline `secret-agent` block. |
| Incremental order | `disable-reordering` | Set `true` to disable reverse-order optimization. |

When **both** storage and destination are present, the routine does not need to exist in the local ABS configuration. ABS still uses `routine` to locate the backup chain in storage. If you override only one side, the routine must exist locally.

Restore to a different named cluster, reading from the routine’s storage:

```json
{

  "routine": "app-daily",

  "time": 1739538000000,

  "destination-name": "staging"

}
```

Cross-region restore when this ABS instance does not define `app-daily`:

```json
{

  "routine": "app-daily",

  "time": 1739538000000,

  "source": {

    "s3-storage": {

      "bucket": "dr-backup-bucket-us-west",

      "path": "prod",

      "s3-region": "us-west-2"

    }

  },

  "destination-name": "local-dr"

}
```

## Restore by path

Copy `key` from `GET /v1/backups/full` into `backup-data-path`. The value is relative to the storage `path` and must not contain `..`. `source` must match that backup’s storage. `destination` is any reachable Aerospike Database cluster.

Terminal window

```shell
curl -s -X POST "$BASE_URL/v1/restore/full" \

  -H "Content-Type: application/json" \

  -d '{

    "destination": {

      "seed-nodes": [{ "host-name": "localhost", "port": 3000 }],

      "credentials": { "user": "restore-user", "password": "password" }

    },

    "policy": { "no-generation": true },

    "source": {

      "s3-storage": {

        "bucket": "company-as-backups",

        "path": "prod",

        "s3-region": "us-east-1"

      }

    },

    "backup-data-path": "app-daily/backup/1739538000000/app"

  }'
```

`no-generation: true` overwrites existing records regardless of generation.

## Restore to the same namespace or a new namespace

By default, ABS restores into the source namespace name. To restore `app` into `app-restore`, set `policy.namespace`:

```json
"policy": {

  "namespace": {

    "source": "app",

    "destination": "app-restore"

  }

}
```

`source` must match the namespace in the backup. It is required as a safeguard against accidental remapping.

A remap applies to exactly one namespace. Every namespace in the restore must equal `source`. Otherwise, ABS rejects the request before the restore starts, with the error `namespace remap from "SOURCE" requires the restore to be scoped to exactly that namespace`.

-   **Restore by path** (`POST /v1/restore/full` or `POST /v1/restore/incremental`): set `backup-data-path` to the backup of a single namespace, which is the `key` that `GET /v1/backups/full` returns. To remap several namespaces, run one restore per namespace.
-   **Restore by timestamp** (`POST /v1/restore/timestamp`): remapping works only for routines that back up a single namespace.

To restore several namespaces without remapping, omit `policy.namespace`. The destination cluster must have namespaces with the same names.

## Unique restores

Set `policy.unique` to `true` so existing records in the destination are left unchanged. Only records that are missing in the destination are inserted.

`unique` cannot be combined with `replace` or `no-generation`.

With the default incremental reordering, ABS applies newer incremental versions first. If you need the newest version of a missing record at the target timestamp, do not set `disable-reordering` to `true`.

```json
{

  "routine": "app-daily",

  "time": 1739538000000,

  "policy": {

    "unique": true

  }

}
```

## Poll job status

Terminal window

```shell
curl -s "$BASE_URL/v1/restore/status/JOB_ID"
```

ABS 3.6.0 and later return lowercase status values:

| Status | Meaning |
| --- | --- |
| `running` | Restore is in progress. |
| `success` | Restore finished successfully. |
| `failure` | Restore failed. |
| `canceled` | Restore was canceled. |

Filter matching on `GET /v1/restore/jobs?status=` is case-insensitive. Legacy aliases `done` and `failed` map to `success` and `failure`. Prefix with `!` to exclude statuses, for example `!failure,canceled`.

### `fresher-records` versus inserts

When you restore into a namespace that already holds the same records, `inserted-records` can stay `0` while `read-records` and `fresher-records` increase. `fresher-records` counts records ABS read from the backup but did not write because the destination already had a generation that won.

That result is success, not a no-op failure. To force backup data to overwrite, use `no-generation: true` (path restore) or restore into an empty namespace.

## Cancel a running restore

Terminal window

```shell
curl -X POST "$BASE_URL/v1/restore/cancel/JOB_ID"
```

ABS cancels the restore job identified by `JOB_ID`. Data that has already been written to the destination cluster remains intact. Prometheus records `outcome="canceled"` when the restore job is canceled.

## Next steps

-   [Run and track restores](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/api-examples#run-and-track-restores)
-   [Monitor ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/monitoring): restore metrics and alerts
-   [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure): encryption keys and Secret Agent on restore