# List workflow job import files

<span id="查询工作流作业导入文件列表"></span>

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

List paginated file-level import records associated with a workflow job, with optional filtering by import file status. Structured load tasks and jobs not associated with an import task return an empty `data.files` array.

```text
GET https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/{workflow_id}/executions/{execution_id}/import-files
```

<span id="调用前准备"></span>

## Before you begin

1. Prepare a [personal access token](../../../../../guides/genesis/api-keys.md#creating-and-managing-personal-access-tokens) with workflow job read permission and the [target workspace ID](../../../../../guides/ai-studio/resource-center/workspace.md#copy-the-workspace-id).
2. Obtain the workflow ID and job ID via [Start workflow job](start-workflow-job.md#successful-response) or [View workflow jobs](list-workflow-jobs.md#successful-response); you can also call [Get workflow job import context](get-workflow-job-import-context.md) first to check whether the job is linked to an import run.

<span id="请求参数"></span>

## Request parameters

Replace `$AI_STUDIO_API_KEY`, `$WORKSPACE_ID`, `$WORKFLOW_ID`, and `$EXECUTION_ID` with actual values.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

### Read the first page

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/import-files" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20"
```

### Filter failed files by status

Status code `3` indicates failed import files. Pass comma-separated integer codes or repeat the `status` query parameter to match multiple statuses.

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/import-files" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20" \
  --data-urlencode "status=3"
```

### Read the next page

Increment `page` by `1` on each request until the cumulative number of returned files reaches `data.total` or `data.files` on the current page is empty.

```bash
curl --get "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/$WORKFLOW_ID/executions/$EXECUTION_ID/import-files" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=2" \
  --data-urlencode "page_size=20"
```

:::::
:::::{tab-item} Parameters

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workflow_id` | string | Yes | Workflow ID. When provided in the path, returns `404` if the target job does not belong to this workflow. |
| `execution_id` | string | Yes | Workflow job ID. |

### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | integer | No | Page number as a non-negative integer; `0` or omitted reads page `1`. Negative or non-integer values return `400`. |
| `page_size` | integer | No | Number of items per page, from `0` to `1000`; `0` or omitted defaults to `20`. Out-of-range or non-integer values return `400`. |
| `status` | string | No | Filter by import file status code. Accepts a single integer, comma-separated integers (such as `2,3`), or repeated `status` query parameters. Valid codes: `1` pending, `2` uploading, `3` failed, `4` succeeded. |

When querying by `execution_id` without specifying `workflow_id`, call `GET https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-apps/executions/{execution_id}/import-files`. To retry failed import files, pass `data.files[].id` of the failed items to [Retry failed files](../../data-connections/import-tasks/retry-failed-import-files.md).

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

`data.total` is the number of files matching the active `status` filter; `data.total_sum` is the total number of files across all statuses in this import run.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "import_context": {
      "task_id": "task-001",
      "task_name": "orders-import",
      "run_id": "run-001",
      "workflow_execution_id": "exec-001",
      "workflow_app_id": "wf-001",
      "moi_task_id": "mowl-task-001",
      "moi_case_id": "mowl-case-001",
      "status": 4,
      "error_message": "1 file failed",
      "row_count": 900,
      "file_count": 4,
      "total": 4,
      "total_success": 3,
      "total_failed": 1,
      "started_at": "2026-08-28T10:00:00Z",
      "ended_at": "2026-08-28T10:02:15Z",
      "created_at": "2026-08-28T09:59:58Z"
    },
    "files": [
      {
        "id": "file-001",
        "name": "orders_20260828.csv",
        "type": 1,
        "status": 3,
        "size": 20480,
        "update_time": 1756375335,
        "reason": "column count mismatch at line 42",
        "user": "alice",
        "start_time": 1756375200,
        "end_time": 1756375335,
        "path": "imports/orders/orders_20260828.csv",
        "run_id": "run-001"
      }
    ],
    "total": 1,
    "total_sum": 4,
    "total_success": 3,
    "total_failed": 1
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` when the request succeeds. |
| `msg` | string | Response status message. |
| `data` | object | Returned payload for this call. |
| `data.import_context` | object | Associated import run context; omitted when the job is not linked to an import task. |
| `data.import_context.task_id` | string | Associated import task ID. |
| `data.import_context.task_name` | string | Import task name. |
| `data.import_context.run_id` | string | Import run record ID. |
| `data.import_context.workflow_execution_id` | string | Associated workflow job ID. |
| `data.import_context.workflow_app_id` | string | Associated workflow ID. |
| `data.import_context.moi_task_id` | string | Server task identifier. |
| `data.import_context.moi_case_id` | string | Server case identifier. |
| `data.import_context.status` | integer | Import run status code: `1` created, `2` running, `3` completed, `4` failed, `5` cancelled. |
| `data.import_context.error_message` | string | Import run error message; omitted when empty. |
| `data.import_context.row_count` | integer | Number of rows processed or written in this import run. |
| `data.import_context.file_count` | integer | File count recorded on the import run; `0` for structured load tasks. |
| `data.import_context.total` | integer | Total files counted across file statuses; `0` for structured load tasks. |
| `data.import_context.total_success` | integer | Number of successfully imported files; `0` for structured load tasks. |
| `data.import_context.total_failed` | integer | Number of failed import files; `0` for structured load tasks. |
| `data.import_context.started_at` | string | Start time in RFC 3339 format; omitted when not recorded. |
| `data.import_context.ended_at` | string | End time in RFC 3339 format; omitted when not recorded. |
| `data.import_context.created_at` | string | Creation time in RFC 3339 format; omitted when not recorded. |
| `data.files` | array of object | Import file records on the current page. Empty when no files match, when the job has no import task, or for structured load tasks. |
| `data.files[].id` | string | Import file record ID. |
| `data.files[].name` | string | File name. |
| `data.files[].type` | integer | File type code. |
| `data.files[].status` | integer | Import file status code: `1` pending, `2` uploading, `3` failed, `4` succeeded. |
| `data.files[].size` | integer | File size in bytes. |
| `data.files[].update_time` | integer | Last update Unix timestamp in seconds; `0` when not recorded. |
| `data.files[].reason` | string | Failure reason for the file import; omitted when empty. |
| `data.files[].user` | string | Username recorded on the import task; omitted when empty. |
| `data.files[].start_time` | integer | Processing start Unix timestamp in seconds; `0` when not recorded. |
| `data.files[].end_time` | integer | Processing end Unix timestamp in seconds; `0` when not recorded. |
| `data.files[].path` | string | Saved file path; omitted when empty. |
| `data.files[].run_id` | string | Associated import run ID. |
| `data.total` | integer | Total number of files matching the active filter. |
| `data.total_sum` | integer | Total number of files across all statuses in this import run. |
| `data.total_success` | integer | Number of succeeded files in this import run. |
| `data.total_failed` | integer | Number of failed files in this import run. |

:::::
::::::
:::::::

<span id="错误响应"></span>

## Error response

An error is returned when pagination parameters are out of range, `status` contains non-integer text, the target job does not exist, or the caller lacks permission to access the job.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "ErrParamInvalid",
  "msg": "Bad Request"
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | Error code. |
| `msg` | string | Readable error message. |

:::::
::::::
:::::::

### Common HTTP errors

```{list-table}
:header-rows: 1

* - HTTP status
  - Error code
  - Common cause
  - Suggested action
* - 400
  - `ErrParamInvalid`, `ErrWorkspaceRequired`
  - `page` is negative, `page_size` is outside `0`–`1000`, `status` is not an integer, or the workspace header is missing.
  - Correct the pagination and status filter parameters before retrying.
* - 401
  - `Unauthorized`
  - Authentication credentials are missing or invalid.
  - Check that the personal access token is valid.
* - 403
  - `ErrForbidden`
  - The current identity cannot read import files for this workflow job.
  - Use an authorized identity, or request access from an administrator.
* - 404
  - `ErrNotFound`
  - The job does not exist, or does not belong to the `workflow_id` specified in the path.
  - Verify `execution_id`, `workflow_id`, and the target workspace.
* - 500
  - `ErrServer`
  - `status` uses an undefined status code, or reading the import file list failed on the server.
  - Use only status codes `1`, `2`, `3`, or `4`, and recheck the import records later.
* - 503
  - `ErrServiceUnavailable`
  - Authorization or storage dependencies are temporarily unavailable.
  - Retry the query later.
```
