# 查询任务列表

列出当前工作区中可读取的导出任务。

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

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。

## 请求体

空对象可用于读取默认列表。也可传入下列筛选和排序字段。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `limit` | integer | 否 | 本页返回条数；不传时为 `20`。 |
| `offset` | integer | 否 | 分页偏移量。 |
| `connector_name` | string | 否 | 按目标连接器名称筛选。 |
| `task_id` | string | 否 | 按导出任务 ID 筛选。 |
| `order_by` | string | 否 | 排序字段：`created_at`、`ended_at`、`status` 或 `name`。 |
| `order_direction` | string | 否 | 排序方向：`asc` 为升序；不传或其他值为降序。 |
| `statuses` | integer（整数数组） | 否 | 按任务状态筛选。 |
| `creator` | string | 否 | 按创建者筛选。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/export/task/list" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  }'
```

## 成功响应

本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`data.tasks[].id` 表示 `data.tasks` 数组中每一项的 `id` 字段。

成功时返回 `200`。`data.tasks` 是当前身份可读取的任务列表，`data.total` 是匹配筛选条件的任务总数。

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

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.tasks` | object（对象数组） | 导出任务列表。 |
| `data.tasks[].id` | string | 任务 ID。 |
| `data.tasks[].name` | string | 任务名称。 |
| `data.tasks[].connector_name` | string | 目标连接器名称。 |
| `data.tasks[].type` | integer | 导出目标类别：`3` 为 MatrixOne，`4` 为 OSS，`5` 为标准 S3。 |
| `data.tasks[].status` | integer | `0` 待处理、`1` 运行中、`2` 已完成、`3` 失败。 |
| `data.tasks[].export_source` | string（二维字符串数组） | 来源文件路径集合。 |
| `data.tasks[].create_time` | string 或 null | 创建时间。 |
| `data.tasks[].end_time` | string 或 null | 结束时间；未结束时为 `null`。 |
| `data.tasks[].fileSuccess` | integer | 已成功导出的文件数。 |
| `data.tasks[].fileFail` | integer | 导出失败的文件数。 |
| `data.total` | integer | 匹配当前筛选条件的任务总数。 |

## 错误响应

服务端业务错误在此兼容接口中可能使用 HTTP `200` 返回。

```json
{
  "code": "ErrServer",
  "msg": "服务器内部错误",
  "data": null
}
```

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - —
  - 请求体无法解析；该兼容路径返回 `error` 字段。
  - 检查分页、状态筛选和排序字段类型。
* - `200`
  - `ErrServer`
  - 列表查询失败。
  - 稍后重试；持续失败时联系管理员。
* - `403`
  - `ErrForbidden`
  - 当前身份没有读取导出任务的权限。
  - 请求授予导出任务读取权限。
* - `503`
  - `ErrCoreAuthorizeUnavailable`
  - 授权服务暂时不可用。
  - 稍后重试。
```

## 后续操作

保存目标任务的 ID，再[查询任务详情](get-export-task.md)或[查询任务状态](get-export-task-state.md)。