---
name: tidb-tools-restore
description: |
  List restore records, get live restore progress, and get restore details
  for a Dedicated cluster. All restore endpoints are Dedicated-only and
  return 501 for other cluster types.
---

# Available Actions

## List Restores

List restore operations for a Dedicated 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 | |

## Get Restore Progress

Get live progress of the active restore operation for a Dedicated cluster.

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

Method: `GET`

This endpoint is cluster-scoped (not restore-scoped), so it does not accept or
echo a restore ID. The current controller always returns `"0"` in `id`.

The service currently folds every upstream progress RPC error—not only a real
not-found response—into HTTP 200 with `not_found: true`. Treat that value as
"progress unavailable or no active restore", and use **List Restores** or
**Get Restore** when the distinction matters.

### 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).

## Get Restore

Get details of a specific restore record.

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

Method: `GET`

- `{restore_id}`: the string `id` returned by the list response (currently a decimal numeric string).

### 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 |