---
name: tidb-tools-backup
description: |
  List TiDB Tools backups, backup settings, and export tasks. Supports Dedicated
  and Premium or Essential v2 logical clusters, with separate APIs and response
  semantics for each architecture.
---

# Available Actions

## Routing and constraints

Resolve the cluster type and service plan before selecting an endpoint. The
backend performs this validation and returns HTTP 501 for an unsupported route.

| Cluster | Supported actions |
|---|---|
| Dedicated | snapshot backups, log backups, Dedicated backup setting, Dedicated backup exports |
| Premium or Essential v2 logical cluster | snapshot backups, NextGen backup setting, NextGen data exports |
| Shared pool, other logical plans, or another cluster type | none of the backup/restore actions in this sub-skill |

All list endpoints accept `page` and `page_size`, defaulting to `1` and `20`.
The general maximum is `200`; **Premium / Essential v2 snapshot backups use a
maximum `page_size` of `100`**. Do not request `log-backups`,
`backup-setting`, or `backup-exports` for a NextGen cluster, and do not use
`nextgen-backup-setting` or `exports` for Dedicated.

## List Snapshot Backups

List snapshot backups for a Dedicated cluster or a supported Premium / Essential
v2 logical cluster.

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

Method: `GET`

### Query parameters

- `page` (integer, optional): page number. Default: `1`.
- `page_size` (integer, optional): page size. Default: `20`. Max: `200` for
  Dedicated and `100` for Premium / Essential v2.

### Response (`ListBackupsResp`)

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

`SnapshotBackup` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `name` | string | |
| `type` | string | `Manual`, `Auto` |
| `status` | string | `running`, `succeeded`, `failed`, `canceled`, `pending` |
| `error_msg` | string | omitted when empty |
| `size_bytes` | int64 | |
| `started_at` | int64 (unix) | |
| `finished_at` | int64 (unix) | omitted when 0 |
| `storage_uri` | string | omitted when empty |
| `tso` | string | omitted when empty |
| `regions` | string[] | omitted when empty |
| `cluster_version` | string | omitted when empty |
| `expire_at` | int64 (unix) | omitted when 0 |
| `protected` | boolean | omitted when false |

The response schema is shared, but NextGen values have different fidelity:

- NextGen `type` reflects the upstream trigger; it does **not** establish that
  the backup is permanent or protected. Treat an omitted `protected` as unknown
  / false, never infer it from a manual trigger.
- NextGen does not expose an operation completion timestamp. `finished_at` can
  be absent even while a backup is active.
- NextGen does not currently provide a backup error message, storage URI, or
  cluster version through this endpoint. Do not fabricate those fields.

## List Log Backups

List continuous log backups (PiTR streams) for a Dedicated cluster.

API Path: `/{cluster_id}/tidbtools/log-backups`

Method: `GET`

### Query parameters

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

### Response (`ListLogBackupsResp`)

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

`LogBackup` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `name` | string | |
| `status` | string | `pending`, `running`, `stopping`, `stopped`, `pausing`, `paused`, `resuming`, `failed`, `scheduled` |
| `error_msg` | string | omitted when empty |
| `checkpoint_timestamp` | int64 | |
| `size_bytes` | int64 | omitted when 0 |
| `created_at` | int64 (unix) | omitted when 0 |
| `started_at` | int64 (unix) | |
| `storage_uri` | string | omitted when empty |
| `regions` | string[] | omitted when empty |
| `truncate_until` | int64 | omitted when 0 |

## Get Backup Setting

Get the automatic backup policy for a Dedicated cluster.

API Path: `/{cluster_id}/tidbtools/backup-setting`

Method: `GET`

### Response (`BackupSetting`)

| Field | Type | Enums |
|---|---|---|
| `schedule` | string | cron expression, e.g. `"0 2 * * *"` |
| `retention_days` | int32 | |
| `encryption_enabled` | boolean | omitted when false |
| `log_backup_enabled` | boolean | |
| `scheduled_status` | string | `enabled`, `paused`, `disabled` |
| `dual_region_enabled` | boolean | omitted when false |
| `dual_regions` | string[] | display names; omitted when empty |
| `next_run_at` | int64 (unix) | omitted when 0 |
| `current_actions` | string[] | in-progress backup operations |

## Get NextGen Backup Setting

Get the backup setting and retention policies for a Premium or Essential v2
logical cluster.

API Path: `/{cluster_id}/tidbtools/nextgen-backup-setting`

Method: `GET`

This is a different schema from the Dedicated `backup-setting` endpoint.

### Response (`NextGenBackupSetting`)

| Field | Type | Notes |
|---|---|---|
| `mode` | string | `standard_bundle` or `flexible_retention` when supplied |
| `retention_days` | integer | omitted when unavailable |
| `daily_backup_time_utc` | string | scheduled UTC time, omitted when unavailable |
| `pitr_start_time` / `pitr_end_time` | int64 (unix) | PiTR coverage, omitted when unavailable |
| `last_modify_time` | int64 (unix) | omitted when unavailable |
| `backup_policies` | `NextGenBackupPolicy[]` | named PiTR/hourly/daily retention policies |
| `unavailable` | boolean | true when a newly restored target has no backup-setting record yet |

`unavailable: true` is an expected transitional state after a NextGen restore,
not a failed request. It is mutually exclusive in practice with a populated
setting; wait for the restore to complete and retry.

`NextGenBackupPolicy` fields are `name`, `description`,
`pitr_retention_days`, `hourly_retention_days`, `daily_retention_days`, and
`daily_start_time_utc`; optional fields are omitted when the upstream policy
does not provide them.

## List Dedicated Backup Exports

List export jobs created from a Dedicated backup.

API Path: `/{cluster_id}/tidbtools/backup-exports`

Method: `GET`

### Response (`ListBackupExportsResp`)

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

`BackupExport` includes its Dedicated `backup_id` and `backup_name`, backup
time, cloud provider/region, sanitized storage location, status, status/error
messages, and creation/completion times. It is **not** the NextGen Export
record described below.

## List NextGen Data Exports

List data-export tasks for a Premium or Essential v2 logical cluster.

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

Method: `GET`

This endpoint is intentionally separate from `backup-exports`: NextGen exports
come from the Export service and are not exports of a Dedicated backup record.

### Response (`ListExportsResp`)

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

`Export` provides `id`, `name`, `source_cluster_id`, snapshot TSO/time,
sanitized storage type/URI and auth type, status (`pending`, `running`,
`succeeded`, `failed`, `canceled`, or `unknown`), timestamps, file/compression
options, table filters, CSV options, and `created_by` when supplied.

Only a failed export has `error_msg`; `status_msg` may contain the upstream
reason for other states. Storage credentials and private-key material are
redacted before the response is returned. Treat redacted values as unavailable
and never attempt to recover or reconstruct credentials from the response.