# Query file list

Filter by volume and query files by page. The request must contain exactly one `volume_id` filter. In the console volume file list, a folder is an entry whose `file_type` is `folder`.

```text
POST https://moi.matrixorigin.cn/newmoi/catalog/file/list
```

## Preparation before calling

First [query the object](list-database-objects.md) in the database to obtain the target volume ID. Prepare the personal access token, target workspace ID, and volume 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`: Target workspace ID, passed through `X-Workspace-ID` Header.
- `$VOLUME_ID`: The volume ID of the file to be listed, passed via `volume_id` in `filters`.

The caller needs read permissions on the target root volume.

## Request example

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/file/list" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": [
      {
        "name": "volume_id",
        "values": ["'"$VOLUME_ID"'"]
      }
    ],
    "page": 1,
    "page_size": 20
  }'
```

## Request body

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | array | Yes | Filter condition array, must contain a condition for `name` to `volume_id`. |
| `filters[].name` | string | Yes | Filter field name. `volume_id` must appear once. You may also pass `parent_id`, `file_name`, or `file_ext`. |
| `filters[].values` | array[string] | Yes | Filter value. `volume_id` must be a single positive integer. `parent_id` is the `id` of the parent `file_type=folder` entry. |
| `filters[].fuzzy` | boolean | No | Whether to use fuzzy matching when `name` is `file_name`. |
| `page` | integer | No | Page number. |
| `page_size` | integer | No | Number of items per page. |
| `order` | string | No | Sort direction: `asc` or `desc`. |
| `order_by` | string | No | Sorting field. |

In this document, `[]` after a type means an array; for example, `string[]` is an array of strings. In field paths, `[]` means each item in an array; for example, `filters[].name` is the `name` field of each item in `filters`.

Omitting `volume_id` and sending only `parent_id` returns `400`. To open the layer that the console labels "Open folder", keep the original `volume_id` and add `parent_id` set to that folder entry's `id`.

## Successful response

Returns `200` and the file list on success. The caller needs read permissions on the target root volume.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 1,
    "list": [
      {
        "id": "file-123",
        "name": "orders.csv",
        "file_type": "file",
        "file_ext": "csv",
        "size": 2048,
        "parent_id": "",
        "volume_id": "789",
        "volume_name": "sales_files",
        "created_at": "2026-01-01T00:00:00Z"
      }
    ]
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.total` | integer | The total number of entries matching the filter criteria. |
| `data.list` | array | List of file and folder entries. |
| `data.list[].id` | string | Entry ID. |
| `data.list[].name` | string | Entry name. |
| `data.list[].file_type` | string | Entry type: `file` or `folder`. `folder` is the "folder" tag in the console file list. |
| `data.list[].workflow_role` | string | Workflow product role; workflow output is `output`, other entries are empty strings. |
| `data.list[].file_ext` | string | File extension. |
| `data.list[].origin_file_name` | string | Original file name; returned when applicable. |
| `data.list[].origin_file_ext` | string | Original file extension; returned when applicable. |
| `data.list[].size` | integer | File size in bytes. |
| `data.list[].parent_id` | string | Parent ID. |
| `data.list[].volume_id` | string | The volume ID to which it belongs. |
| `data.list[].volume_name` | string | The name of the volume to which it belongs. |
| `data.list[].volume_reserved` | boolean | Whether the volume it belongs to is a reserved volume. |
| `data.list[].created_at` | string | Creation time, in RFC 3339 format. |
| `data.list[].created_by` | string | Creator ID. |
| `data.list[].ref_file_id` | string | The associated source file ID; returned when applicable. |
| `data.list[].parsed_file_id` | string | The file ID of the downloadable analysis product; returned when applicable. |
| `data.list[].ref_workflow_id` | string | Association workflow ID; returned when applicable. |

## Error response

```json
{
  "code": "ErrParamInvalid",
  "msg": "必须提供唯一的 volume_id 筛选条件",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `400`
  - `ErrParamInvalid`
  - The unique positive integer `volume_id` filter was not passed in.
  - Keep only one `volume_id` in `filters`.
* - `403`
  - `ErrForbidden`
  - The current identity does not have read permissions on the target root volume.
  - Check workspace and volume authorization.
* - `404`
  - `ErrNotFound`
  - The target volume does not exist.
  - Check `volume_id`.
* - `500`
  - `ErrServer`
  - The service cannot read the file list.
  - Record the request time and error message and try again; if it continues to fail, contact support.
```

## Follow-up operations

Use `data.list[].id` to [Query file details](get-file.md). When `file_type` is `folder`, call this API again with the current `volume_id` and that entry's `id` as `parent_id`. That request matches the console "Open folder" action.