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

# List Files

> List directory contents in the sandbox using the HopX VM Agent API. Browse filesystem structure, view file metadata including size and modification times, and navigate directories. Learn how to use GET /files/list endpoint to list files and directories with filtering options. Includes request examples and response formats.

List files and directories in a specified path. Returns metadata including size, permissions, and modification time.

## Endpoint

```
GET /files/list
```

## Request

### Headers

```
Authorization: Bearer YOUR_JWT_TOKEN
```

### Query Parameters

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `path`    | string | No       | Directory path (default: `/workspace`) |

### Example Request

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/list?path=/workspace" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Response

### Success (200 OK)

```json theme={null}
{
  "files": [
    {
      "name": "data.txt",
      "path": "/workspace/data.txt",
      "size": 1024,
      "is_directory": false,
      "permissions": "rw-r--r--",
      "modified_time": "2025-01-28T00:00:00Z"
    },
    {
      "name": "scripts",
      "path": "/workspace/scripts",
      "size": 4096,
      "is_directory": true,
      "permissions": "rwxr-xr-x",
      "modified_time": "2025-01-28T00:00:00Z"
    }
  ]
}
```

## Status Codes

| Code | Description         |
| ---- | ------------------- |
| 200  | Success             |
| 401  | Unauthorized        |
| 404  | Directory not found |

## Use Cases

### Browse Workspace

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/list?path=/workspace" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | jq '.files[] | {name, size, is_directory}'
```

### Find Large Files

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/list?path=/workspace" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq '.files[] | select(.size > 1000000) | {name, size}'
```

### List Only Directories

```bash theme={null}
curl "https://sandbox_abc123xyz.hopx.dev/files/list?path=/workspace" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" | \
  jq '.files[] | select(.is_directory == true) | .name'
```

## Related

* **SDK**: [sandbox.files.list()](/sdk/python/files#list) - Python SDK method
* [CLI File Operations](/cli/commands/files) - File operations from CLI

## Next Steps

* **[Read File](/api/vm-agent/read-file)** - Read file contents
* **[File Exists](/api/vm-agent/file-exists)** - Check if file exists