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

# Managing files

> How Browserbase Agents work with files, and retrieve downloads.

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](/platform/agents/how-it-works). For the API that returns files, see the [Downloads API](/platform/browser/files/downloads).

## 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](/platform/browser/files/downloads) using the `sessionId` from the run.

First, get the run's `sessionId` from [Get a run](/reference/api/get-a-run). Then list the downloads for that session with [List downloads](/reference/api/list-downloads):

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.browserbase.com/v1/downloads?sessionId=$SESSION_ID" \
      --header "x-bb-api-key: $BROWSERBASE_API_KEY"
    ```
  </Tab>

  <Tab title="Node.js">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

Fetch a single file by ID with [Get a download](/reference/api/get-a-download). You can also filter the list by `filename`, `mimeType`, or size. See the [Downloads](/platform/browser/files/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:

<Warning>
  * **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](/platform/browser/files/downloads) 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.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Downloads API" icon="download" iconType="sharp-solid" href="/platform/browser/files/downloads">
    Retrieve files an agent downloads during a run
  </Card>

  <Card title="How it works" icon="gear" iconType="sharp-solid" href="/platform/agents/how-it-works">
    The execution loop, built-in tools, and run lifecycle
  </Card>

  <Card title="Integrating agents" icon="plug" iconType="sharp-solid" href="/platform/agents/integrate-api-sdk">
    Trigger runs and track them from your application
  </Card>

  <Card title="List downloads" icon="code" iconType="sharp-solid" href="/reference/api/list-downloads">
    API reference for listing a session's downloads
  </Card>
</CardGroup>