---
name: tidb-tools-dm
description: |
  List and inspect DM migration jobs and precheck results for a cluster.
  Supports both Dedicated and Premium cluster types.
---

# Available Actions

## Get DM Overview

Get the DM version information for a cluster.

API Path: `/{cluster_id}/tidbtools/dm/overview`

Method: `GET`

For Dedicated clusters, the controller queries ConfigCenter when that client is
configured. Premium clusters return an empty overview. If the ConfigCenter
client is absent, the Dedicated response is also empty; if the configured
ConfigCenter request fails, the endpoint fails rather than returning an empty
version.

Response (`DMOverview`):

| Field | Type | Notes |
|---|---|---|
| `version` | string | effective image tag; empty when ConfigCenter is unavailable |
| `version_source` | string | `"config-center"` or empty |

## List DM Jobs

List DM migration jobs for a cluster.

API Path: `/{cluster_id}/tidbtools/dm/jobs`

Method: `GET`

### Query parameters

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

For Premium clusters, `page` is validated but not forwarded because the
upstream API is page-token based. Only `page_size` is forwarded, and this
endpoint does not expose a continuation token.

### Response (`ListDMJobsResp`)

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

`DMJob` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `name` | string | |
| `status` | string | `running`, `paused`, `finished`, `failed`, `stopped`, `unknown` |
| `source_type` | string | |
| `target_cluster` | string | |
| `mode` | string | `full`, `incremental`, `all` |
| `conn_method` | string | |
| `created_at` | int64 (unix) | |
| `updated_at` | int64 (unix) | |
| `error_msg` | string | omitted when empty |

## Get DM Job

Get details of a single DM job including its sub-tasks.

API Path: `/{cluster_id}/tidbtools/dm/jobs/{job_id}`

Method: `GET`

- `{job_id}`: numeric job ID (Dedicated) or string job ID (Premium).

### Response (`DMJobDetail`)

All `DMJob` fields (see above) plus:

| Field | Type |
|---|---|
| `sub_tasks` | `DMSubTask[]` |

`DMSubTask` fields:

| Field | Type | Enums |
|---|---|---|
| `name` | string | |
| `mode` | string | `full`, `incremental`, `all` |
| `status` | string | `running`, `paused`, `finished`, `failed`, `stopped`, `unknown` |
| `progress_percent` | int32 | omitted when nil |
| `binlog_position` | string | |
| `binlog_ts` | int64 | |
| `rows_per_sec` | int64 | omitted when nil |

## List DM Prechecks

List DM precheck runs for a cluster.

API Path: `/{cluster_id}/tidbtools/dm/prechecks`

Method: `GET`

### Query parameters

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

For Premium clusters, `page` is validated but not forwarded because the
upstream API is page-token based. Only `page_size` is forwarded, and this
endpoint does not expose a continuation token.

### Response (`ListDMPrechecksResp`)

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

`DMPrecheck` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `dm_job_name` | string | |
| `status` | string | canonical values: `passed`, `failed`, `warning`, `running`; see compatibility note below |
| `started_at` | int64 (unix) | |
| `finished_at` | int64 (unix) | |
| `finished` | int32 | completed check count |
| `total` | int32 | total check count |
| `errmsg` | string | |

The Dedicated converter normalizes known upstream values but passes through
unrecognized values unchanged. Treat `status` as an open string rather than a
strict enum; for example, a Dedicated precheck detail may currently return
`finished`.

## Get DM Precheck

Get the detail of a DM precheck run including per-item results.

API Path: `/{cluster_id}/tidbtools/dm/prechecks/{precheck_id}`

Method: `GET`

- `{precheck_id}`: numeric precheck ID (Dedicated) or string precheck ID (Premium).

### Response (`DMPrecheckDetail`)

All `DMPrecheck` fields (see above) plus:

| Field | Type |
|---|---|
| `items` | `DMPrecheckItem[]` |

`DMPrecheckItem` fields:

| Field | Type | Enums |
|---|---|---|
| `name` | string | |
| `status` | string | canonical values: `passed`, `failed`, `warning`, `running`; unknown Dedicated upstream values may pass through |
| `result` | string | |
| `errmsg` | string | |