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

# List files in a sandbox directory (/api/v1/sandbox/{id}/files/list)

> Returns a listing of files and directories at the specified path within the sandbox Served by the live controller (answers 401 unauthenticated) but absent from…

Returns a listing of files and directories at the specified path within the sandbox

Served by the live controller (answers 401 unauthenticated) but absent from its published `/openapi.json` — verified 2026-08-31.

### Path parameters

<ParamField path="id" type="string (uuid)" required>
  Unique sandbox identifier
</ParamField>

### Query parameters

<ParamField query="path" type="string">
  Directory path to list (relative to sandbox root)
</ParamField>

<ParamField query="recursive" type="boolean">
  Whether to list files recursively
</ParamField>

### Response

`FileListResponse`

<ResponseField name="files" type="FileListEntry[]">
  <Expandable title="FileListEntry">
    <ResponseField name="name" type="string">
      File or directory name
    </ResponseField>

    <ResponseField name="path" type="string">
      Full path within the sandbox
    </ResponseField>

    <ResponseField name="type" type="string">
      Whether this entry is a file or directory
    </ResponseField>

    <ResponseField name="size" type="integer">
      File size in bytes (0 for directories)
    </ResponseField>

    <ResponseField name="modified_at" type="string (date-time)">
      Last modification timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

### Status codes

| Code  | Meaning      |
| ----- | ------------ |
| `200` | File listing |
| `400` | —            |
| `401` | —            |
| `404` | —            |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.sandbox.stateset.app/api/v1/sandbox/{id}/files/list' \
    --header "Authorization: Bearer $STATESET_SANDBOX_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "files": [
      {
        "name": "Two-Person Tent",
        "path": "string",
        "type": "file",
        "size": 1,
        "modified_at": "2026-08-31T14:22:05Z"
      }
    ]
  }
  ```
</ResponseExample>