Create task¶

Create an export task to write selected files or processing results to object storage or MatrixOne. A successful response indicates that the task has been accepted; use the returned task ID to query the actual processing status of each file.

POST https://moi.matrixorigin.cn/newmoi/export/task/create

Preparation before calling¶

First Query exportable files or select the file on the creation page and confirm that the target connector is available. Prepare a personal access token with access to the target workspace, target workspace ID, target connector information, and file information to be exported.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$CONNECTOR_ID: Target connector ID, fill in the connector_id field of the request body.

The page will automatically pair the target connector, type and config. When calling the API directly, you should also keep the three objects of the same target type, otherwise the task may not be executed correctly. files contains at least one file; each file requires a file ID and full path.

Request example¶

Export processing results to MatrixOne¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/export/task/create" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "task_name": "export-orders",
    "creator": "data-engineer",
    "connector_id": "'$CONNECTOR_ID'",
    "connector_name": "target-mo",
    "type": 3,
    "config": {
      "mo_config": {
        "database_name": "analytics",
        "table_name": "orders",
        "new_table": true,
        "duplicated_strategy": 3,
        "column": {
          "export_column": [
            {
              "source_column": "content",
              "mapping_column": "content"
            }
          ],
          "combine_column": []
        }
      }
    },
    "files": [
      {
        "file_id": "file_01",
        "full_path": [
          "volume_01",
          "orders.csv"
        ],
        "is_raw": false
      }
    ]
  }'

Export raw files to standard S3¶

The following example exports a raw file to the exports/ path of the standard S3 connector and uses Gzip compression.

curl -X POST "https://moi.matrixorigin.cn/newmoi/export/task/create" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "task_name": "export-to-s3",
    "creator": "data-engineer",
    "connector_id": "'$CONNECTOR_ID'",
    "connector_name": "target-s3",
    "type": 5,
    "config": {
      "s3_config": {
        "path": "exports/",
        "need_compress": true,
        "compress_method": "gzip"
      }
    },
    "files": [
      {
        "file_id": "file_01",
        "full_path": [
          "volume_01",
          "orders.csv"
        ],
        "is_raw": true
      }
    ]
  }'

Request body¶

Field	Type	Is it required	Description
`task_name`	string	Yes	Export task name.
`creator`	string	Yes	The creator’s ID.
`connector_id`	string	Yes	The target connector ID.
`connector_name`	string	Yes	The target connector name.
`type`	integer	Yes	Export target category: `3` for MatrixOne, `4` for OSS, `5` for standard S3. The page generates this value based on the selected connector.
`config`	object	Yes	Target configuration. It cannot be `null`; provide only the configuration object for the selected `type`.
`files`	object[]	Yes	List of files to export.
`files[].file_id`	string	Yes	Source file ID.
`files[].full_path`	string[]	Yes	The full path of the source file.
`files[].ref_file_id`	string	No	The reference file ID corresponding to the original file. Can be used to correlate raw files when exporting vectorized processing results.
`files[].parsed_file_id`	string	No	Parsed product file ID. Fill in when exporting parsed or vectorized processing results.
`files[].is_raw`	boolean	No	`true` means to export the original file; `false` means to export the processing result. The currently created page will pass this field explicitly.

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

Fill in `config` according to the target¶

Object Storage and MatrixOne use different configuration objects; only one object corresponding to type is filled in in a request. The “condition required” in the table means that it must be provided when selecting the corresponding export target; the subfields are the content that needs to be filled in when the currently created page completes the configuration of the target.

Field	Type	Is it required	Description
`config.s3_config`	object	Required	The target configuration for OSS or standard S3.
`config.s3_config.path`	string	Condition required	The export path in the target bucket. The currently created page requires ending with `/`.
`config.s3_config.need_compress`	boolean	Condition required	Whether to package and compress this file and export it.
`config.s3_config.compress_method`	string	Condition required	The current created page uses `gzip` or `no`; set to `gzip` when `gzip` is selected.
`config.mo_config`	object	Condition required	Target table configuration for MatrixOne.
`config.mo_config.database_name`	string	Required condition	Target database name.
`config.mo_config.table_name`	string	Condition required	Target table name; when creating a new table, it is the new table name.
`config.mo_config.new_table`	boolean	Condition required	Whether to create a new target table.
`config.mo_config.duplicated_strategy`	integer	Condition required	Duplicate data processing method: `1` overwrite, `2` skip, `3` retain. Use `3` when creating a new table on the current page.
`config.mo_config.column`	object	Condition required	Export column and column mapping configuration.
`config.mo_config.column.export_column`	object[]	Condition required	The column mapping to be written. Each item contains `source_column` and `mapping_column`.
`config.mo_config.column.export_column[].source_column`	string	Condition required	The source column name in the processing result.
`config.mo_config.column.export_column[].mapping_column`	string	Condition required	Column name in the target table.
`config.mo_config.column.combine_column`	string[]	Condition required	The name of the source column to be merged; if not merging, pass an empty array.

Successful response¶

Returns 200 on success. data is a newly created task object; the task starts running after it is created. A successful request only means that the task has been accepted, but does not mean that the file has been exported.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "export-task-123",
    "name": "export-to-matrixone",
    "connector_name": "target-mo",
    "type": 3,
    "status": 1,
    "export_source": [["volume-001", "reports", "summary.csv"]],
    "create_time": "2026-08-18T10:00:00Z",
    "end_time": null,
    "fileSuccess": 0,
    "fileFail": 0
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	string	Create a new task ID for subsequent query, retry or deletion.
`data.name`	string	Task name.
`data.connector_name`	string	Target connector name.
`data.type`	integer	Export target category: `3` for MatrixOne, `4` for OSS, `5` for standard S3.
`data.status`	integer	Task status: `0` pending, `1` running, `2` completed, `3` failed.
`data.export_source`	string[][]	A collection of source paths of files to be exported.
`data.create_time`	string or null	Creation time.
`data.end_time`	string or null	End time; `null` if not ended.
`data.fileSuccess`	integer	The number of files that have been successfully exported.
`data.fileFail`	integer	The number of files that failed to export.

Error response¶

When parameter or business verification fails, the current compatible interface may still return HTTP 200, so the code of the response must be checked at the same time.

{
  "code": "ErrParamInvalid",
  "msg": "Invalid request parameters",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`200`	`ErrParamInvalid`	The request body cannot be parsed, or the exported configuration and source files do not meet the requirements.	Check `config`, connector id and `file_id`, `full_path` of each file.
`200`	`ErrServer`	The target connector is not available, the source file cannot be parsed, or the task creation failed.	Confirm that the connector is available and the source files are still accessible and try again.
`403`	`ErrForbidden`	The current identity does not have permission to create export tasks or use target connectors.	Request permissions for the appropriate workspace and connector.
`503`	`ErrCoreAuthorizeUnavailable`	Authorization service is temporarily unavailable.	Try again later; if it continues to fail, contact your administrator.

Follow-up operations¶

Record data.id as the task ID used for subsequent queries. Successful creation only means that the task has been accepted. Use this ID to query task status: continue querying if there are still files waiting or being processed; when both the waiting and processing numbers are 0, this processing has ended. If all are successful, no further operation is required; if there is a failure, Query Export Files locates the failed item.

Last updated on Sep 3, 2026