---
name: tidb-tools-restore
description: |
  List restore records, get restore progress or diagnostics, and get restore
  details for Dedicated and Premium or Essential v2 logical clusters.
---

# Available Actions

## Routing and identifiers

These endpoints support Dedicated clusters and Premium / Essential v2 logical
clusters only. Other cluster types and service plans return HTTP 501.

Dedicated restore records are ordinary restore jobs and use their returned
numeric `id`. A NextGen restore is target-cluster scoped rather than a
source-cluster job list: its sole stable restore ID is the **target cluster
ID**. For a Premium / Essential v2 call, therefore use the requested
`{cluster_id}` as `{restore_id}` for the detail endpoint.

## List Restores

List restore operations for a Dedicated cluster, or the current restore status
for a Premium / Essential v2 logical cluster.

API Path: `/{cluster_id}/tidbtools/restores`

Method: `GET`

### Query parameters

- `page` (integer, optional): page number. Default: `1`.
- `page_size` (integer, optional): page size. Default: `20`. Max: `200`.

### Response (`ListRestoresResp`)

| Field | Type |
|---|---|
| `items` | `Restore[]` |
| `total` | integer |

`Restore` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `name` | string | |
| `mode` | string | `snapshot`, `pitr` |
| `source_backup_name` | string | |
| `backup_id` | string | omitted when empty |
| `log_backup_id` | string | omitted when empty |
| `restored_ts` | string | omitted when empty |
| `restored_at` | int64 (unix) | omitted when 0 |
| `target_cluster_id` | string | |
| `restore_region` | string | omitted when empty |
| `status` | string | `pending`, `running`, `succeeded`, `failed`, `terminated`, `unknown` |
| `error_msg` | string | omitted when empty |
| `started_at` | int64 (unix) | |
| `finished_at` | int64 (unix) | omitted when 0 |
| `progress_percent` | int32 | |

For Premium / Essential v2, the endpoint returns zero or one item for the
target cluster. When present, the item ID and `target_cluster_id` both equal
the requested cluster ID; it has a generated `restore-{cluster_id}` name.
It reports `error_msg` only when its status is `failed`. Requesting `page > 1`
returns no items (with `total: 1` if a current restore record exists).

## Get Restore Progress

Get live progress for a Dedicated restore or durable operator diagnostics for a
Premium / Essential v2 restore.

API Path: `/{cluster_id}/tidbtools/restores/progress`

Method: `GET`

This endpoint is cluster-scoped (not restore-scoped). For Dedicated, the
current controller returns `"0"` in `id`; do not use it as a restore identifier.
An explicit upstream NotFound returns HTTP 200 with `not_found: true`; other
upstream failures are preserved as request errors. Use **List Restores** or
**Get Restore** when you need durable record details.

### Response (`RestoreProgress`)

| Field | Type | Notes |
|---|---|---|
| `id` | string | currently always `"0"`; do not use as a restore identifier |
| `progress_percent` | int32 | |
| `status` | string | human-readable current stage or overall status |
| `steps` | `RestoreStepProgress[]` | omitted when empty |
| `rate_bytes_per_sec` | int64 | currently not populated; returned as `0` |
| `eta_seconds` | int64 | currently not populated and omitted |
| `updated_at` | int64 (unix) | currently not populated; returned as `0` |
| `restore_bytes` | int64 | omitted when 0 |
| `error` | `RestoreErrorDetail` | omitted when nil |
| `not_found` | boolean | true when progress is unavailable or no restore is active; omitted when false |

`RestoreStepProgress` fields: `step_name` (string), `progress` (float64).

`RestoreErrorDetail` fields: `message` (string), `retryable` (boolean).

### NextGen diagnostics

For Premium / Essential v2, `id` is the target cluster ID and the response is
a durable NextGen restore view. In addition to the common status, progress,
message, and failed-only `error`, it can include:

| Field | Meaning |
|---|---|
| `target` | target cluster identity, state, location, plan, version, ownership, and provisioning timestamps |
| `source_cluster_id` / `source` | durable source-cluster association and source metadata when exposed |
| `backup` | source backup association and metadata when it can be retrieved |
| `audit` | restore mode, point-in-time, and restore event time |
| `restore_started_at`, `restore_finished_at`, `duration_seconds` | restore timing derived from durable metadata when available |
| `source_metadata_available` / `source_metadata_note` | whether source/backup association is available and any lookup limitation |
| `runtime_diagnostic` | why runtime-only diagnostics are unavailable, when applicable |

`not_found: true` means no current NextGen restore record exists. Runtime
diagnostics may be unavailable because ng-global does not expose the regional
restore ID; this does not invalidate the durable status, target, source, or
backup fields. Do not substitute the target cluster ID for a regional restore
ID or infer missing timestamps/source metadata.

## Get Restore

Get details of a specific restore record.

API Path: `/{cluster_id}/tidbtools/restores/{restore_id}`

Method: `GET`

- Dedicated: `{restore_id}` is the string `id` returned by the list response
  (currently a decimal numeric string).
- Premium / Essential v2: `{restore_id}` must be the requested target
  `{cluster_id}`. Any other numeric ID returns not found.

### Response (`RestoreDetail`)

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `created_at` | int64 (unix) | |
| `backup_id` | string | |
| `cluster_id` | string | |
| `status` | string | `pending`, `running`, `succeeded`, `failed`, `terminated`, `unknown` |
| `cluster` | `RestoreClusterInfo` | omitted when nil |

`RestoreClusterInfo` fields:

| Field | Type |
|---|---|
| `id` | string |
| `name` | string |
| `status` | string |