---
name: tidb-tools-import
description: |
  List import jobs and tasks for a cluster.
  Dedicated clusters use the standard Import service (imports endpoint).
  Premium clusters use IMPORT INTO tasks (import-into-tasks endpoint).
---

# Available Actions

## List Imports (Dedicated)

List import jobs for a Dedicated cluster.

Returns `501 Not Implemented` for Premium clusters — use **List Import-Into Tasks** instead.

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

Method: `GET`

### Query parameters

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

### Response (`ListImportsResp`)

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

`DedicatedImport` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `name` | string | |
| `source_type` | string | `LOCAL_FILE`, `S3`, `GCS` |
| `file_type` | string | `CSV`, `SQL`, `PARQUET` |
| `target_database` | string | |
| `target_table` | string | |
| `filter` | string | |
| `conn_method` | string | |
| `status` | string | `pending`, `preparing`, `running`, `succeeded`, `failed`, `canceled` |
| `error_msg` | string | |
| `total_rows` | int64 | |
| `imported_rows` | int64 | |
| `size_bytes` | int64 | |
| `total_tables_count` | int32 | |
| `completed_tables` | int32 | |
| `pending_tables` | int32 | |
| `completed_percent` | int32 | |
| `post_import_completed_percent` | int32 | |
| `created_at` | int64 (unix) | |
| `finished_at` | int64 (unix) | omitted when 0 |

## List Import-Into Tasks (Premium)

List IMPORT INTO tasks for a Premium cluster.

Returns `501 Not Implemented` for Dedicated clusters — use **List Imports** instead.

API Path: `/{cluster_id}/tidbtools/import-into-tasks`

Method: `GET`

### Query parameters

- `page` (integer, optional): validated by the controller but not forwarded.
  Default: `1`.
- `page_size` (integer, optional): page size. Default: `20`. Max: `200`.

The upstream API is page-token based. Only `page_size` is forwarded, and this
endpoint does not expose a continuation token.

### Response (`ListImportIntoTasksResp`)

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

`PremiumImportIntoTask` fields:

| Field | Type | Enums |
|---|---|---|
| `id` | string | |
| `name` | string | |
| `sql_statement` | string | |
| `status` | string | `pending`, `preparing`, `running`, `succeeded`, `failed`, `canceled` |
| `error_msg` | string | |
| `source_uri` | string | |
| `conn_method` | string | |
| `created_at` | int64 (unix) | |
| `finished_at` | int64 (unix) | omitted when 0 |
| `progress_percent` | int32 | |
| `total_tables_count` | int32 | |
| `completed_tables` | int32 | |
| `pending_tables` | int32 | |
| `completed_percent` | int32 | |
| `post_import_completed_percent` | int32 | |

## Get Import-Into Task (Premium)

Get details of a single Premium IMPORT INTO task.

Returns `501 Not Implemented` for Dedicated clusters.

API Path: `/{cluster_id}/tidbtools/import-into-tasks/{task_id}`

Method: `GET`

Response is a single `PremiumImportIntoTask` object (same fields as list items above).