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

# List Workspace Files

> List files and directories in the task's sandbox workspace. Supports recursive listing.

This endpoint lists files and directories inside the sandbox workspace associated with a task run. By default it lists the top-level contents of `/vercel/sandbox`. Use the `path` and `recursive` parameters to navigate subdirectories.

## Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:

1. Go to [app.blackbox.ai/agent-api](https://app.blackbox.ai/agent-api) and click **Get an API Key** (requires a Pro subscription)
2. Once provisioning completes, you will be redirected to your [Dashboard](https://app.blackbox.ai/dashboard)
3. From the Dashboard, create an API key to use with all Agent API requests

Your API key will be in the format: `sk-xxxxxxxxxxxxxxxxxxxxxx`

## Headers

<ParamField header="Authorization" type="string" required>
  API Key of the form `Bearer <api_key>`.

  Example: `Bearer sk_b41b647ffbfed27f616560`
</ParamField>

## Path Parameters

<ParamField path="runId" type="string" required>
  The unique run identifier returned when the task was created.

  Example: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
</ParamField>

## Query Parameters

<ParamField query="path" type="string" default="/vercel/sandbox">
  Directory path to list inside the sandbox.

  Default: `/vercel/sandbox`

  Example: `path=/vercel/sandbox/src`
</ParamField>

<ParamField query="recursive" type="boolean" default="false">
  Whether to list files recursively in all subdirectories.

  Default: `false`

  Example: `recursive=true`
</ParamField>

## Response Fields

<ResponseField name="files" type="array">
  Array of file and directory entries.

  <Expandable title="File Entry">
    <ResponseField name="name" type="string">
      File or directory name.
    </ResponseField>

    <ResponseField name="path" type="string">
      Full absolute path inside the sandbox.
    </ResponseField>

    <ResponseField name="type" type="string">
      `"file"` or `"directory"`.
    </ResponseField>

    <ResponseField name="size" type="number | null">
      File size in bytes. `null` for directories.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="path" type="string">
  The directory path that was listed.
</ResponseField>

<ResponseField name="recursive" type="boolean">
  Whether the listing was recursive.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```bash cURL - Recursive theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files?recursive=true' \
    -H 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  const API_KEY = "YOUR_API_KEY";
  const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

  const response = await fetch(
    `https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files?recursive=true`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  const data = await response.json();
  data.files.forEach(f => console.log(`${f.type}\t${f.path}\t${f.size ?? "-"}`));
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import requests

  API_KEY = "YOUR_API_KEY"
  RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  response = requests.get(
      f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files",
      headers={"Authorization": f"Bearer {API_KEY}"},
      params={"recursive": "true"},
  )
  data = response.json()
  for f in data["files"]:
      print(f"{f['type']}\t{f['path']}\t{f.get('size', '-')}")
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "files": [
      {
        "name": "src",
        "path": "/vercel/sandbox/src",
        "type": "directory",
        "size": null
      },
      {
        "name": "package.json",
        "path": "/vercel/sandbox/package.json",
        "type": "file",
        "size": 1024
      },
      {
        "name": "README.md",
        "path": "/vercel/sandbox/README.md",
        "type": "file",
        "size": 512
      },
      {
        "name": "README.fr.md",
        "path": "/vercel/sandbox/README.fr.md",
        "type": "file",
        "size": 648
      }
    ],
    "path": "/vercel/sandbox",
    "recursive": false
  }
  ```

  ```json Error - No Sandbox theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "error": "No sandbox available for this task"
  }
  ```
</ResponseExample>

## Error Codes

| Status Code | Error                 | Description                            |
| ----------- | --------------------- | -------------------------------------- |
| 200         | Success               | File list returned                     |
| 401         | Unauthorized          | Invalid or missing API key             |
| 403         | Forbidden             | Task belongs to a different user       |
| 404         | Not Found             | Task not found or no sandbox available |
| 500         | Internal Server Error | Failed to list files                   |