List Workspace Files

GEThttps://agent.blackbox.ai/api/v1/tasks/{runId}/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:

Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
Once provisioning completes, you will be redirected to your Dashboard
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

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Path Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Query Parameters

pathstringdefault: /vercel/sandbox

Directory path to list inside the sandbox.

Default: /vercel/sandbox

Example: path=/vercel/sandbox/src

recursivebooleandefault: false

Whether to list files recursively in all subdirectories.

Default: false

Example: recursive=true

Response Fields

filesarray

Array of file and directory entries.

File Entry

namestring

File or directory name.

pathstring

Full absolute path inside the sandbox.

typestring

"file" or "directory".

sizenumber | null

File size in bytes. null for directories.

pathstring

The directory path that was listed.

recursiveboolean

Whether the listing was recursive.

Request Example

curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files' \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files?recursive=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'

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 ?? "-"}`));

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', '-')}")

Response Example

{
  "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
}

{
  "error": "No sandbox available for this task"
}

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