# Query task list

Lists the import tasks in the current workspace that you have read permission for. First get the task ID from the response, then query the details, files and running records.

```text
GET https://moi.matrixorigin.cn/newmoi/task/list
```

## Before you call

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: The workspace ID to be queried, passed through the `X-Workspace-ID` Header.

## Request example

```bash
curl "https://moi.matrixorigin.cn/newmoi/task/list?page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## Query parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `page` | integer | No | Page number. The default value is `1`. |
| `page_size` | integer | No | Number of items per page. The default value is `20`. |
| `keyword` | string | No | Keyword filter. |
| `order_by` | string | No | Order field: `name`, `created_at`, `updated_at`, `started_at`, `ended_at`, `status`, `start_at` or `end_at`. Defaults to sorting by `created_at`. |
| `is_desc` | boolean | No | Whether to descend in descending order; if not passed in, it will be in descending order. |
| `status` | integer[] | No | Filter by task status; can be passed in repeatedly. Status codes: `0` Unknown, `1` In progress, `2` On hold, `3` Paused, `4` Completed, `5` Failed. |
| `connector_sources` | integer[] | No | Filter by connector source type; can be passed in repeatedly. |
| `load_interval_types` | integer[] | No | Filter by load cycle type; can be passed in repeatedly. `0` unknown, `1` every day, `2` every hour, `3` every minute, `4` once, `5` every 5 minutes, `6` every 10 minutes, `7` every 30 minutes, `8` every 2 hours, `9` every 4 hours, `10` every 6 hours, `11` every 12 hours. |
| `source_connector_ids` | string[] | No | Filter by source connector ID; can be passed in repeatedly. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

## Successful response

Returns `200` on success. Save the task ID and do not infer the ID from the name.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "tasks": [
      {
        "id": "task_01",
        "name": "import_orders",
        "config_type": 1,
        "source_connector_id": "conn_01",
        "connector_name": "orders_mysql",
        "volume_id": "vol_01",
        "status": 2,
        "total_rows": 100,
        "imported_rows": 100,
        "success_file_count": 1,
        "failed_file_count": 0
      }
    ],
    "total": 1
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.tasks` | object[] | Tasks readable by the current caller. See [Import task object fields](import-task-object-fields.md) for the complete fields of each element. |
| `data.tasks[].id` | string | Task ID. |
| `data.tasks[].name` | string | Task name. |
| `data.tasks[].config_type` | integer | Task configuration type: `1` file import, `2` database import, `3` structured load. |
| `data.tasks[].source_connector_id` | string | Source connector ID. |
| `data.tasks[].source_connector_type` | integer | Source connector type code. |
| `data.tasks[].connector_name` | string | Source connector name. |
| `data.tasks[].volume_id` | string | Target Volume ID. |
| `data.tasks[].volume_name` | string | Target Volume name. |
| `data.tasks[].volume_path` | object | The path identifier in the target Volume. |
| `data.tasks[].volume_path.id_list` | string[] | IDs at each path level. |
| `data.tasks[].volume_path.name_list` | string[] | Names at each path level. |
| `data.tasks[].creator` | string | The user ID that created the task. |
| `data.tasks[].status` | integer | Task current status code: `0` Unknown, `1` In Progress, `2` Paused, `3` Paused, `4` Completed, `5` Failed. |
| `data.tasks[].source_config` | object | Type-specific source configuration. |
| `data.tasks[].start_at` | integer | Start time as a Unix timestamp. |
| `data.tasks[].end_at` | integer | End time as a Unix timestamp. |
| `data.tasks[].created_at` | integer | Creation time as a Unix timestamp. |
| `data.tasks[].updated_at` | integer | Update time as a Unix timestamp. |
| `data.tasks[].file_types` | integer[] | File type filtering code. |
| `data.tasks[].path_regex` | string | File path filtering regular expression; empty string if not set. |
| `data.tasks[].unzip_keep_structure` | boolean | Whether to keep the directory structure when decompressing files. |
| `data.tasks[].dedup` | object | Deduplication configuration; `null` when not set. |
| `data.tasks[].dedup.by` | string[] | Fields used for deduplication. |
| `data.tasks[].dedup.strategy` | string | Deduplication strategy. |
| `data.tasks[].table_path` | object | Single table target path identifier. |
| `data.tasks[].table_paths` | object[] | Multi-table target path identifier; may be omitted if there is no multi-table configuration. |
| `data.tasks[].table_path.id_list` | string[] | IDs at each level in the single-table target path. |
| `data.tasks[].table_path.name_list` | string[] | Names at each level in the single-table target path. |
| `data.tasks[].table_paths[].id_list` | string[] | IDs at each level in a multi-table target path. |
| `data.tasks[].table_paths[].name_list` | string[] | Names at each level in a multi-table target path. |
| `data.tasks[].source_files` | string[][] | Source file information; each element is the connector name followed by the file URI. |
| `data.tasks[].load_type` | integer | Loading method code. |
| `data.tasks[].load_results` | object[] | The loading results of each file or table. |
| `data.tasks[].load_results[].lines` | integer | Number of lines in this result. |
| `data.tasks[].load_results[].reason` | string | Failure reason for this result. |
| `data.tasks[].total_rows` | integer | Total number of rows in the task. |
| `data.tasks[].imported_rows` | integer | Number of imported rows. |
| `data.tasks[].success_file_count` | integer | Number of successful files. |
| `data.tasks[].failed_file_count` | integer | Number of failed files. |
| `data.tasks[].latest_rows` | object | Row statistics for the latest run; may be omitted when not collected. |
| `data.tasks[].cumulative_rows` | object | Cumulative row statistics; may be omitted when not collected. |
| `data.tasks[].latest_rows.read_rows` | integer | Rows read in the latest run. |
| `data.tasks[].latest_rows.succeeded_rows` | integer | Rows successfully processed in the latest run. |
| `data.tasks[].latest_rows.failed_rows` | integer | Rows that failed in the latest run. |
| `data.tasks[].latest_rows.skipped_rows` | integer | Rows skipped in the latest run. |
| `data.tasks[].latest_rows.complete` | boolean | Whether statistics for the latest run are complete. |
| `data.tasks[].cumulative_rows.read_rows` | integer | Cumulative rows read. |
| `data.tasks[].cumulative_rows.succeeded_rows` | integer | Cumulative rows successfully processed. |
| `data.tasks[].cumulative_rows.failed_rows` | integer | Cumulative rows that failed. |
| `data.tasks[].cumulative_rows.skipped_rows` | integer | Cumulative rows skipped. |
| `data.tasks[].cumulative_rows.complete` | boolean | Whether cumulative statistics are complete. |
| `data.tasks[].error_code` | string | Current error code; may be omitted if there is no error. |
| `data.tasks[].error_summary` | string | Current error summary; may be omitted if there is no error. |
| `data.tasks[].target_path_state` | string | Target path state. |
| `data.tasks[].target_path_error_code` | string | Error code when target path parsing or verification fails; may be omitted if there is no error. |
| `data.tasks[].target_path_error_summary` | string | Error summary when target path parsing or verification fails; may be omitted if there is no error. |
| `data.tasks[].structured_load_config` | object | The complete configuration for structured loading; may only be returned if `config_type` is `3`. |
| `data.tasks[].structured_load_summary` | object | Structured load summary; may only be returned if `config_type` is `3`, contains source, target, mapping, schedule, backfill, progress, checkpoint and reconciliation summary. |
| `data.tasks[].structured_load_summary.source_type` | string | Structured load source type. |
| `data.tasks[].structured_load_summary.source_object` | string | Structured load source object. |
| `data.tasks[].structured_load_summary.target_database_id` | string | Target database ID. |
| `data.tasks[].structured_load_summary.target_table_id` | string | Target table ID. |
| `data.tasks[].structured_load_summary.target_table_name` | string | Target table name. |
| `data.tasks[].structured_load_summary.source.connector_id` | string | Source connector ID; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.source.connector_name` | string | Source connector name; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.source.source_type` | string | Source object type; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.source.database` | string | Source database name; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.source.schema` | string | Source schema name; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.source.table` | string | Source table name; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.source.collection` | string | Source collection name; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.source.object` | string | Source object name; may be omitted when not applicable. |
| `data.tasks[].structured_load_summary.target.mode` | string | Target write mode. |
| `data.tasks[].structured_load_summary.target.database_id` | string | Target database ID. |
| `data.tasks[].structured_load_summary.target.database_name` | string | Target database name. |
| `data.tasks[].structured_load_summary.target.table_id` | string | Target table ID. |
| `data.tasks[].structured_load_summary.target.table_name` | string | Target table name. |
| `data.tasks[].structured_load_summary.mapping_count` | integer | Number of mappings. |
| `data.tasks[].structured_load_summary.backfill_progress_percent` | integer | Backfill progress percentage. |
| `data.tasks[].structured_load_summary.mapping` | JSON | Mapping configuration. |
| `data.tasks[].structured_load_summary.schedule` | JSON | Schedule configuration. |
| `data.tasks[].structured_load_summary.backfill` | JSON | Backfill configuration. |
| `data.tasks[].structured_load_summary.run_mode` | string | Run mode. |
| `data.tasks[].structured_load_summary.sync_strategy` | string | Synchronization strategy. |
| `data.tasks[].structured_load_summary.backfill_phase` | string | Backfill phase. |
| `data.tasks[].structured_load_summary.runtime_init_status` | string | Runtime initialization status. |
| `data.tasks[].structured_load_summary.priority` | string | Priority. |
| `data.tasks[].structured_load_summary.config_hash` | string | Configuration hash. |
| `data.tasks[].structured_load_summary.backfill_enabled` | boolean | Whether to enable backfill. |
| `data.tasks[].structured_load_summary.progress.total_rows` | integer | Total rows in loading progress; `progress` may be omitted when there is no progress information. |
| `data.tasks[].structured_load_summary.progress.imported_rows` | integer | Imported rows in loading progress; `progress` may be omitted when there is no progress information. |
| `data.tasks[].structured_load_summary.progress.progress_percent` | integer | Loading progress percentage; `progress` may be omitted when there is no progress information. |
| `data.tasks[].structured_load_summary.checkpoint.source_object_hash` | string | Checkpoint source object hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.structured_config_hash` | string | Checkpoint structured configuration hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.source_schema_hash` | string | Checkpoint source schema hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.capability_profile_hash` | string | Checkpoint capability profile hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.order_policy_hash` | string | Checkpoint order policy hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.consistency_proof_hash` | string | Checkpoint consistency proof hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.lock_owner_run_id` | string | Checkpoint lock owner run ID; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.lock_phase` | string | Checkpoint lock phase; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_load_summary.checkpoint.lock_expires_at` | integer | Expiration Unix timestamp of the checkpoint lock; may be omitted if there is no lock. |
| `data.tasks[].structured_load_summary.reconcile.id` | string | Reconciliation record ID; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_load_summary.reconcile.run_id` | string | Reconciliation run ID; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_load_summary.reconcile.phase` | string | Reconciliation phase; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_load_summary.reconcile.status` | string | Reconciliation status; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_load_summary.reconcile.error_code` | string | Reconciliation error code; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_load_summary.reconcile.error_message` | string | Reconciliation error message; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_load_summary.reconcile.created_table_id` | string | Table ID created during reconciliation; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_load_summary.reconcile.updated_at` | integer | Reconciliation record update time as a Unix timestamp. |
| `data.tasks[].structured_load_summary.reconcile.resolved_at` | integer | Reconciliation record resolution time as a Unix timestamp. |
| `data.tasks[].structured_runtime` | object | Structured load runtime information; may only be returned when `config_type` is `3`, including initialization status, configuration hash, running status, checkpoints, backfill, mapping, progress, reconciliation and the latest run. |
| `data.tasks[].structured_runtime.runtime_init_status` | string | Runtime initialization status. |
| `data.tasks[].structured_runtime.config_hash` | string | Runtime configuration hash. |
| `data.tasks[].structured_runtime.run_status` | string | Run status. |
| `data.tasks[].structured_runtime.checkpoint_status` | string | Checkpoint status. |
| `data.tasks[].structured_runtime.backfill` | JSON | Backfill data. |
| `data.tasks[].structured_runtime.schema_snapshot` | JSON | Schema snapshot data. |
| `data.tasks[].structured_runtime.mapping` | JSON | Mapping data. |
| `data.tasks[].structured_runtime.progress.total_rows` | integer | Total rows in loading progress; `progress` may be omitted when there is no progress information. |
| `data.tasks[].structured_runtime.progress.imported_rows` | integer | Imported rows in loading progress; `progress` may be omitted when there is no progress information. |
| `data.tasks[].structured_runtime.progress.progress_percent` | integer | Loading progress percentage; `progress` may be omitted when there is no progress information. |
| `data.tasks[].structured_runtime.checkpoint.source_object_hash` | string | Checkpoint source object hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.structured_config_hash` | string | Checkpoint structured configuration hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.source_schema_hash` | string | Checkpoint source schema hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.capability_profile_hash` | string | Checkpoint capability profile hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.order_policy_hash` | string | Checkpoint order policy hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.consistency_proof_hash` | string | Checkpoint consistency proof hash; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.lock_owner_run_id` | string | Checkpoint lock owner run ID; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.lock_phase` | string | Checkpoint lock phase; may be omitted when there is no checkpoint. |
| `data.tasks[].structured_runtime.checkpoint.lock_expires_at` | integer | Expiration Unix timestamp of the checkpoint lock; may be omitted if there is no lock. |
| `data.tasks[].structured_runtime.reconcile.id` | string | Reconciliation record ID; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_runtime.reconcile.run_id` | string | Reconciliation run ID; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_runtime.reconcile.phase` | string | Reconciliation phase; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_runtime.reconcile.status` | string | Reconciliation status; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_runtime.reconcile.error_code` | string | Reconciliation error code; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_runtime.reconcile.error_message` | string | Reconciliation error message; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_runtime.reconcile.created_table_id` | string | Table ID created during reconciliation; may be omitted when there is no reconciliation information. |
| `data.tasks[].structured_runtime.reconcile.updated_at` | integer | Reconciliation record update time as a Unix timestamp. |
| `data.tasks[].structured_runtime.reconcile.resolved_at` | integer | Reconciliation record resolution time as a Unix timestamp. |
| `data.tasks[].structured_runtime.last_run.id` | string | Most recent run ID; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.run_status` | string | Most recent run status; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.error_message` | string | Error message from the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.source_schema_hash` | string | Source schema hash from the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.source_object_hash` | string | Source object hash from the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.structured_config_hash` | string | Structured configuration hash from the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.trigger_id` | string | Trigger ID of the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.trigger_source` | string | Trigger source of the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.workflow_execution_id` | string | Workflow execution ID of the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.mowl_task_id` | string | MOWL task ID of the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.moi_case_id` | string | MOI case ID of the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.current_phase` | string | Current phase of the most recent run; may be omitted when there is no run record. |
| `data.tasks[].structured_runtime.last_run.status` | integer | The status code of the last run. |
| `data.tasks[].structured_runtime.last_run.row_count` | integer | Rows processed in the most recent run. |
| `data.tasks[].structured_runtime.last_run.file_count` | integer | Files processed in the most recent run. |
| `data.tasks[].structured_runtime.last_run.scheduled_fire_at` | integer | Scheduled firing time of the most recent run as a Unix timestamp. |
| `data.tasks[].structured_runtime.last_run.started_at` | integer | Start time of the most recent run as a Unix timestamp. |
| `data.tasks[].structured_runtime.last_run.ended_at` | integer | End time of the most recent run as a Unix timestamp. |
| `data.tasks[].structured_runtime.last_run.created_at` | integer | Creation time of the most recent run as a Unix timestamp. |
| `data.tasks[].structured_runtime.last_run.updated_at` | integer | Update time of the most recent run as a Unix timestamp. |
| `data.tasks[].mapping` | JSON | Structured load mapping configuration; may only be returned if `config_type` is `3`. |
| `data.tasks[].schedule` | JSON | Structured load schedule configuration; may only be returned if `config_type` is `3`. |
| `data.tasks[].backfill` | JSON | Structured load backfill configuration; may only be returned if `config_type` is `3`. |
| `data.tasks[].runtime_init_status` | string | Structured load initialization status; may only be returned if `config_type` is `3`. |
| `data.tasks[].priority` | string | Structured load priority; may only be returned if `config_type` is `3`. |
| `data.tasks[].config_hash` | string | Structured load configuration hash; may only be returned if `config_type` is `3`. |
| `data.tasks[].structured_config_hash` | string | Structured load configuration hash; may only be returned if `config_type` is `3`. |
| `data.total` | integer | The total number of tasks matching the condition. |

In this document, `[]` after a type means an array; for example, `string[]` is an array of strings. In field paths, `[]` means each item in an array; for example, `data.tasks[].id` is the `id` field of each item in `data.tasks`.

## Error response

```json
{
  "code": "ErrForbidden",
  "msg": "permission denied",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 25 30 33

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `ErrParamInvalid`
  - The query parameter is invalid.
  - Fix paging or filtering parameters.
* - `403`
  - `ErrForbidden`
  - The caller does not have permission to read the task collection.
  - Check workspace authorization.
* - `503`
  - `ErrCoreAuthorizeUnavailable`
  - The service is temporarily unable to complete authorization screening.
  - Try again later; don't treat an empty list as no tasks.
* - `200`
  - `ErrServer`
  - The service failed to list tasks.
  - Check both HTTP status and `code`.
```

## Follow-up operations

Save the ID of the target task and then [query task details](get-import-task.md).