Managing files - Browserbase Documentation

Agents work with real files, not just page content. Each run gets a sandboxed file workspace where the agent can read and write files, process documents it downloads, and produce output. This is what lets an agent fetch a PDF, read a spreadsheet, or pull a report rather than only scraping text from a page. For the broader tool set, see How it works. For the API that returns files, see the Downloads API.

What the agent can do with files

Read and write files in its sandboxed workspace during a run.
Process downloaded content such as PDFs and spreadsheets.
Produce output files like CSVs or spreadsheets from data it gathers.
Extract small inline tables directly from a page when the data is compact.

The agent decides when files are the fastest path. A run that needs to compare figures across a downloaded report, for example, may download the file and process it rather than reading the page.

Retrieving files the agent downloads

When the agent downloads a file during a run, Browserbase stores it against the run’s browser session. Retrieve it with the Downloads API using the sessionId from the run. First, get the run’s sessionId from Get a run. Then list the downloads for that session with List downloads:

cURL
Node.js
Python

curl "https://api.browserbase.com/v1/downloads?sessionId=$SESSION_ID" \
  --header "x-bb-api-key: $BROWSERBASE_API_KEY"

const response = await fetch(
  `https://api.browserbase.com/v1/downloads?sessionId=${sessionId}`,
  {
    headers: { "x-bb-api-key": process.env.BROWSERBASE_API_KEY! },
  },
);

const { downloads } = await response.json();
console.log(downloads);

import os
import requests

response = requests.get(
    "https://api.browserbase.com/v1/downloads",
    headers={"x-bb-api-key": os.environ["BROWSERBASE_API_KEY"]},
    params={"sessionId": session_id},
)

downloads = response.json()["downloads"]
print(downloads)

Fetch a single file by ID with Get a download. You can also filter the list by filename, mimeType, or size. See the Downloads guide for the full workflow.

Use cases

Files unlock the document-heavy tasks that scripts struggle with:

Document fetching: SOC2 reports, authorization forms, and transaction documents from vendor and provider sites.
Government and real estate records: tax documents and property records that download as PDFs.
Data export: gather records across pages, then write a single spreadsheet as output.

Limitations

The file workflow is still growing. Plan around these limits:

You can’t upload files to an agent yet. The agent works with files it creates or downloads during the run.
Large, paginated tabular data can’t be reliably exported inline. Trigger a download and retrieve the file through the Downloads API instead of asking the agent to extract a large table.
Large files (over 1 MB) should flow through downloads, not inline extraction. The agent can extract small <table> elements directly, but bigger payloads belong in a download.

Next steps

Downloads API

Retrieve files an agent downloads during a run

How it works

The execution loop, built-in tools, and run lifecycle

Integrating agents

Trigger runs and track them from your application

List downloads

API reference for listing a session’s downloads

​What the agent can do with files

​Retrieving files the agent downloads

​Use cases

​Limitations

​Next steps