> ## 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

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

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

### Path parameters

<ParamField path="sandboxId" 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/{sandboxId}/files/list' \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "files": [
      {
        "name": "string",
        "path": "string",
        "type": "file",
        "size": 1,
        "modified_at": "2026-07-24T12:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>