# 查询导出文件

列出导出任务中的文件及每个文件的处理状态。

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

## 调用前准备

先[查询任务详情](get-export-task.md)，确认要查看的导出任务。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和导出任务 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$TASK_ID`：要查看文件的导出任务 ID，填写请求体的 `task_id` 字段。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `task_id` | string | 是 | 要查询文件的导出任务 ID。 |
| `limit` | integer | 否 | 本页返回条数；不传时为 `20`。 |
| `offset` | integer | 否 | 分页偏移量。 |
| `statuses` | integer（整数数组） | 否 | 按文件状态筛选。 |
| `order_by` | string | 否 | 排序字段：`created_at`、`started_at`、`ended_at` 或 `status`。 |
| `order_direction` | string | 否 | 排序方向：`asc` 为升序；不传或其他值为降序。 |

## 请求示例

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

## 成功响应

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

成功时返回 `200`。`data.files` 返回每个导出记录及其状态；`details` 可用于定位失败原因。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "files": [{
      "id": "export-file-001",
      "file_name": "summary.csv",
      "file_type": "csv",
      "status": 3,
      "full_path": ["volume-001", "reports", "summary.csv"],
      "details": "<失败说明>",
      "create_time": "2026-08-18T10:00:00Z",
      "start_time": "2026-08-18T10:01:00Z",
      "end_time": "2026-08-18T10:02:00Z"
    }],
    "total": 1,
    "total_success": 0,
    "total_failure": 1,
    "total_files": 1
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.files` | object（对象数组） | 导出文件记录列表。 |
| `data.files[].id` | string | 导出记录 ID；用于指定重试文件。 |
| `data.files[].file_name` | string | 文件名称。 |
| `data.files[].file_type` | string | 由文件名识别出的扩展名。 |
| `data.files[].status` | integer | `0` 待处理、`1` 导出中、`2` 已完成、`3` 失败。 |
| `data.files[].full_path` | string（字符串数组） | 源文件完整路径。 |
| `data.files[].details` | string | 处理详情或失败说明。 |
| `data.files[].create_time` | string 或 null | 创建时间。 |
| `data.files[].start_time` | string 或 null | 开始导出时间；尚未开始时为 `null`。 |
| `data.files[].end_time` | string 或 null | 结束时间；尚未结束时为 `null`。 |
| `data.total` | integer | 本页匹配的记录数。 |
| `data.total_success` | integer | 任务中已成功导出的文件总数。 |
| `data.total_failure` | integer | 任务中导出失败的文件总数。 |
| `data.total_files` | integer | 任务中的全部文件总数。 |

## 错误响应

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - —
  - 请求体无法解析；该兼容路径返回 `error` 字段。
  - 传入有效 `task_id`，并检查分页和状态筛选类型。
* - `200`
  - `ErrServer`
  - 任务不存在或文件记录查询失败。
  - 核对任务 ID 后重试。
* - `403`
  - `ErrForbidden`
  - 当前身份没有读取该任务的权限。
  - 请求授予导出任务读取权限。
```

## 后续操作

将失败文件 ID 用于[重新运行任务](rerun-export-task.md)；重试后[查询任务状态](get-export-task-state.md)确认是否清零失败数。