# Query file list

Lists files accessible to a connector. First get the file `uri` from the response and then preview the file.

```text
GET $CLOUDSIGMA_API_BASE/connectors/files/list
```

## Before you call this API

Configure the [regional API endpoint and authentication](https://omnifabric.cloudsigma.com/docs/developer/endpoints-and-authentication.html.md), and select the target workspace.

Only connectors that support file enumeration can call this interface.

Set the operation-specific values used in the request:

- `$CONNECTOR_ID`: The connector ID of the file to be enumerated, passed through the `connector_id` query parameter.

## Request example

```bash
curl "$CLOUDSIGMA_API_BASE/connectors/files/list?connector_id=$CONNECTOR_ID&limit=20" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## Query parameters

| Parameters | Type | Is it required | Description |
| --- | --- | --- | --- |
| `connector_id` | string | Yes | The connector ID. |
| `cursor` | string | No | The cursor returned from the previous page. |
| `limit` | integer | No | This page returns the quantity. The default value is `20`. |
| `dir` | string | no | Directory relative to the connector configuration root. |
| `file_types` | integer[] | No | Filter only the file type codes of ordinary files. Pass this parameter repeatedly, for example `file_types=7&file_types=25`. Directories are always returned and are not filtered by this parameter. |

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


### File type codes

`file_types` and response `type` use these codes:

| Code | Type | Code | Type |
| --- | --- | --- | --- |
| `0` | Unrecognized | `1` | TXT |
| `2` | PDF | `3` | Generic image |
| `4` | PPT | `5` | Word |
| `6` | Markdown | `7` | CSV |
| `8` | Parquet | `9` | SQL |
| `10` | Table of contents | `11` | DOCX |
| `12` | PPTX | `13` | WAV |
| `14` | MP3 | `15` | AAC |
| `16` | FLAC | `17` | MP4 |
| `18` | MOV | `19` | MKV |
| `20` | PNG | `21` | JPG |
| `22` | JPEG | `23` | BMP |
| `24` | XLS | `25` | XLSX |
| `27` | HTM | `28` | HTML |
| `29` | EML | `30` | MSG |
| `31` | P7S | `32` | DWG |
| `33` | DXF | `34` | FAS |
| `35` | DOC | `101` | ZIP |
| `102` | RAR | `103` | 7Z |
| `104` | TAR | `105` | TAR.GZ |
| `106` | TAR.BZ2 | `107` | GZ |
| `108` | BZ2 |  |  |

`limit` is the amount used by the connector when reading a page. After applying `file_types` filter, the actual number of ordinary files returned by this page may be less than `limit`. Connectors that support cursor paging return the next page cursor when `has_more` is `true`; connectors that do not support paging return an empty cursor and `has_more=false`.

## Successful response

Returns `200` on success.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "files": [
      {
        "uri": "/orders.csv",
        "filename": "orders.csv",
        "size": 1024,
        "type": 1,
        "path": "/",
        "create_time": 0,
        "update_time": 0
      }
    ],
    "cursor": "next_cursor",
    "has_more": true
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.files` | object[] | Current page file; may be omitted or empty array when there is no file. |
| `data.files[].uri` | string | File URI, which can be used for subsequent previews. |
| `data.files[].filename` | string | File name. |
| `data.files[].size` | integer | File size in bytes. |
| `data.files[].type` | integer | File type code. |
| `data.files[].path` | string | File path within the connector. |
| `data.files[].create_time` | integer | The Unix timestamp of the file creation time. The current file list implementation returns `0`. |
| `data.files[].update_time` | integer | Unix timestamp of when the file was updated. The current file list implementation returns `0`. |
| `data.cursor` | string | Next page cursor. Only used for next request if `data.has_more` is `true`. |
| `data.has_more` | boolean | Whether there is still a next page. |

In field paths, `[]` means each item in an array. For example, `data.files[].uri` is the `uri` field of each item in `data.files`.

## Error response

```json
{
  "code": "ErrServer",
  "msg": "server error",
  "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`
  - `—`
  - The query parameter format is invalid. The response uses the `error` field and does not use the standard `code` field.
  - Fix `connector_id`, cursor or `limit` and try again.
* - `500`
  - `ErrServer`
  - The connector does not exist, is not accessible, does not support enumerating files, or the service failed to read the file list.
  - Check the connector ID and access permissions; verify that the connector supports file enumeration and try again.
```

## Follow-up operations

Save the `uri` and connector ID of the target file. When you need to confirm the file content, use these two values ​​[preview file](https://omnifabric.cloudsigma.com/docs/reference/api/ai-studio/data-connections/connector-files/preview-file.html.md).