List workflow job import files

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.

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

Before you begin

  1. Prepare a personal access token with workflow job read permission and the target workspace ID.

  2. Obtain the workflow ID and job ID via Start workflow job or View workflow jobs; you can also call Get workflow job import context first to check whether the job is linked to an import run.

Request parameters

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

Read the first page

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.

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.

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"

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.

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.

{
  "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
  }
}

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.

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.

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

Field

Type

Description

code

string

Error code.

msg

string

Readable error message.

Common HTTP errors

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.

Last updated on