# 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.

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

## Preparation before calling

First [Query exportable files](list-exportable-files.md) 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

```bash
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.

```bash
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.

```json
{
  "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.

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 24 36 28

* - 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](get-export-task-state.md): 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](list-export-task-files.md) locates the failed item.