# Query task file

List the files and processing results in an import task. Based on the file status and failure reason, decide whether to retry the failed file.

```text
GET https://moi.matrixorigin.cn/newmoi/task/files?task_id=$TASK_ID
```

## Before you call

Prepare the personal access token, target workspace ID, and task ID that have access to the target workspace.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: The workspace ID of the task to be queried, passed through the `X-Workspace-ID` Header.
- `$TASK_ID`: Import task ID.

## Request example

```bash
curl "https://moi.matrixorigin.cn/newmoi/task/files?task_id=$TASK_ID&page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## Query parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `task_id` | string | Yes | The import task ID to be queried. |
| `page` | integer | No | Page number. The default value is `1`. |
| `page_size` | integer | No | Number of items per page. The default value is `20`. |
| `status` | integer[] | No | Filter by file processing status; can be passed in repeatedly. Status code: `0` no status, `1` waiting for processing, `2` uploading, `3` processing failed, `4` processing successful. |

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

## Successful response

Returns `200` on success.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "files": [
      {
        "id": "file_01",
        "name": "orders.csv",
        "type": 1,
        "status": 2,
        "size": 1024,
        "update_time": 1735632000,
        "reason": "",
        "user": "reader",
        "start_time": 1735632000,
        "end_time": 1735632060,
        "path": "/orders.csv"
      }
    ],
    "total": 1,
    "total_sum": 1,
    "total_success": 1,
    "total_failed": 0
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.files` | object[] | Current page task file. |
| `data.files[].id` | string | File ID. |
| `data.files[].name` | string | File name. |
| `data.files[].type` | integer | File type code. |
| `data.files[].status` | integer | Processing status code. |
| `data.files[].size` | integer | File size in bytes. |
| `data.files[].other_metadata` | string | Additional metadata for the file; an empty string if there is no additional metadata. |
| `data.files[].reason` | string | Reason for failure. |
| `data.files[].user` | string | The user ID associated with the file. |
| `data.files[].path` | string | File path. |
| `data.files[].start_time` | integer | Unix timestamp of when processing started. |
| `data.files[].end_time` | integer | The Unix timestamp of the end processing time. |
| `data.files[].update_time` | integer | The Unix timestamp of the last update time. |
| `data.total` | integer | The number of files returned by the current query. |
| `data.total_sum` | integer | Total number of all files. |
| `data.total_success` | integer | The total number of successful files. |
| `data.total_failed` | integer | Total number of failed files. |

## Error response

```json
{
  "code": "ErrServer",
  "msg": "server error",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 25 30 33

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `ErrParamInvalid`
  - The query parameter is invalid.
  - Fix `task_id` or paging parameter.
* - `200`
  - `ErrServer`
  - The service failed to query the task file.
  - Check both HTTP status and `code`.
```

## Follow-up operations

Pass only the `id` of the failed file to [retry-failed-import-files.md].