---
title: "List files"
method: GET
path: "/v2/file-systems/{file_system_key}/files"
tags: ["File Systems"]
---

# List files

`GET /v2/file-systems/{file_system_key}/files`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/file-systems/{file_system_key}/files`
- Auth: HTTP bearer

Lists the files and folders stored in a file system. An empty path lists the file system root.

## Path parameters

- `file_system_key` string, required

## Query parameters

- `path` string
- `depth` integer
- `max_entries` integer

## Response `200`

Successfully retrieved the directory listing.

- ListFileSystemFilesResponse
  - `path` string, required: Folder that was listed, relative to the file system root
  - `depth` integer, required: Number of folder levels that were walked
  - `entries` FileEntry[], required
    - `path` string, required: Path of the entry relative to the file system root
    - `name` string, required: Final path component
    - `type` 'file' | 'dir' | 'symlink' | 'other', required: Kind of entry
    - `size_bytes` string, required: Size of the entry in bytes
    - `modified` string, required: Last modification time of the entry
  - `entry_count` integer, required: Number of entries returned
  - `truncated` boolean, required: Whether the listing stopped at max_entries

## Other responses

- `403`: Not permitted for this key, project or workspace. See https://docs.orq.ai/reference/errors for the error codes.
- `404`: File system or path not found.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-23** `0b4e519a544f`: 1 info
  - added the non-success response with the status `403`
- **2026-10-23** `732aed62833a`: 1 info
  - removed the non-success response with the status `403`
- **2026-10-22** `4f826b2c3a0e`: 1 info
  - added the non-success response with the status `403`
- **2026-10-22** `8f0dc569f247`: 1 info
  - removed the non-success response with the status `403`
- **2026-10-21** `08b800d640e6`: 1 info
  - added the non-success response with the status `403`

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/file-systems/:file_system_key/files/get.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)