> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List application files

> List the files and directories at a path inside an application with GET /v2/apps/{app_id}/files, each with its type, size and last-modified time.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

Requires an API key with the `files:read` [scope](/en/api-reference/authentication#scopes).

List Files returns the files and directories at a given path inside an application, each entry carrying its type, size, and last-modified time. Use it to browse an application's storage from a dashboard or script before reading, writing, or deleting a specific file.

The listing reflects the application's storage on its cluster node at request time; it is not cached. Pair it with [Read File](/en/api-reference/endpoint/apps/filemanager/content) to fetch a file's contents, or [Create/Modify File](/en/api-reference/endpoint/apps/filemanager/put) to write one. Omitting `path` lists the application root.

On workspace-shared applications the caller needs the `maintain` or `admin` [role](/en/api-reference/endpoint/workspace/members/invite#roles), and members without the restricted-files permission never see `.env` or `.env.production` in the results, those entries are filtered out of the response rather than erroring.

## Parameters

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  The ID of the application. You can find this in the URL of your application's dashboard.
</ParamField>

<ParamField query="path" type="string" placeholder="Path to list" required>
  The path of the directory whose files you want to list, up to 256 characters. Default is the root directory.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful: `success` if it was, `error` if not.
</ResponseField>

<ResponseField name="response" type="array">
  The list of files and directories in the specified path.

  <Expandable title="Toggle object">
    <ResponseField name="type" type="string">
      The type of the entry. Can be `file` or `directory`.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the file or directory.
    </ResponseField>

    <ResponseField name="size" type="number">
      The size of the file in bytes. For directories, it is 0.
    </ResponseField>

    <ResponseField name="lastModified" type="number">
      The last modified timestamp of the file or directory in milliseconds since the epoch.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
      "status": "success",
      "response": [
          {
              "type": "file",
              "name": ".env",
              "size": 86,
              "lastModified": 1676168978000
          },
          {
              "type": "file",
              "name": ".gitignore",
              "size": 8,
              "lastModified": 1675125328000
          },
          {
              "type": "file",
              "name": "index.js",
              "size": 614,
              "lastModified": 1676168350000
          },
          {
              "type": "file",
              "name": "squarecloud.app",
              "size": 65,
              "lastModified": 1676169188000
          },
          {
              "type": "directory",
              "name": "src",
              "lastModified": 1676155738000
          }
      ]
  }
  ```
</ResponseExample>

## Common errors

| Code | HTTP | Meaning |
| - | - | - |
| `INVALID_PATH` | 400 | The `path` query parameter failed validation (traversal, invalid characters, or longer than 256 characters), or the cluster could not read the directory. |
| `BLOCKED_PATH` | 403 | The requested path is inside a blocked directory. |
| `FILE_NOT_FOUND` | 404 | The directory does not exist. |

## Related

* CLI: [`squarecloud app file list`](/en/cli-reference/files#squarecloud-app-file-list)
* SDKs: [`api.apps.files.list()`](/en/sdks/js/managing_files) (JavaScript), [`client.apps.files.list()`](/en/sdks/py/managing_files) (Python), [`c.Apps.Files.List()`](/en/sdks/go/managing_files) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.