---
name: tidb-tools-backup
description: |
  List snapshot and log backups and get backup settings for a Dedicated cluster.
  All backup endpoints are Dedicated-only and return 501 for other cluster types.
---

# Available Actions

## List Snapshot Backups

List snapshot backups for a Dedicated 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`.

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

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