Skip to main content
Unlike screenshots saved locally, files downloaded during browser automation are stored in Browserbase’s cloud storage. Retrieve them with the Browserbase SDK. A common use case for headless browsers is downloading files from web pages. Browserbase syncs every downloaded file to cloud storage and appends a Unix timestamp to avoid naming conflicts (e.g., sample.pdf becomes sample-1719265797164.pdf).
View or run the example template here

Triggering downloads

First, trigger a download in your browser automation:
  1. Create a browser session and get the session ID
  2. Connect to the session using your preferred framework
  3. Configure your library’s downloads location
  4. Perform the download action in your automation script
Critical: setDownloadBehavior ConfigurationWhen using Playwright or Puppeteer, you must call Browser.setDownloadBehavior via CDP to ensure downloads are synced to Browserbase’s storage. Pay special attention to the downloadPath parameter. It must be set to "downloads" exactly as shown in the examples above.Common misconfiguration issues:
  • Using an absolute path (e.g., /tmp/downloads) instead of "downloads"
  • Omitting the setDownloadBehavior call entirely
  • Setting behavior to something other than "allow"
Without proper configuration, your downloads won’t be available for retrieval.
Opening a PDF URL in a browser session also triggers a download to Browserbase’s cloud storage. To view the PDF instead of downloading it, configure your browser settings as shown here.

Retrieving downloaded files

After triggering downloads, retrieve them with the SDK. downloads.list, downloads.retrieve, downloads.download, and downloads.delete call the Downloads API. You can list, filter, retrieve, and delete individual files.
These examples need @browserbasehq/sdk 2.27.0 or later, and browserbase 1.26.0 or later.
Filenames don’t include the timestamp suffix Browserbase adds during storage.
Files sync in real time, but large downloads may not be immediately available through the /downloads endpoint. The code below includes retry logic to handle this.

List downloads

List all downloads for a session with optional filtering by filename, MIME type, file size, and creation time.
Node.js

Filtering options

Example with filters:
Node.js

Get a download

Retrieve metadata with downloads.retrieve, or the file bytes with downloads.download.
Node.js

Delete a download

Remove a download from storage. Returns 204 No Content on success.
Node.js

Download object

Each download contains the following fields:

List downloads

List and filter downloads

Get download

Get metadata or file content

Delete download

Remove a download

Browser files

Work with files in browser sessions.