The Downloads API provides granular control over files downloaded during browser sessions. You can list, filter, retrieve, and delete individual downloads.
This API is currently available to select customers. Contact support if you’d like access.
Filenames are returned without the timestamp suffix that Browserbase adds during storage.
List Downloads List all downloads for a session with optional filtering by filename, MIME type, file size, and creation time.
const API_KEY = process . env . BROWSERBASE_API_KEY ! ; const sessionId = "your-session-id" ; const response = await fetch ( `https://api.browserbase.com/v1/downloads?sessionId= ${ sessionId } ` , { headers: { "x-bb-api-key" : API_KEY }, } ); const { downloads , total } = await response . json (); console . log ( `Found ${ total } downloads` ); for ( const download of downloads ) { console . log ( `- ${ download . filename } ( ${ download . size } bytes)` ); }
import os import requests API_KEY = os.environ[ "BROWSERBASE_API_KEY" ] session_id = "your-session-id" response = requests.get( "https://api.browserbase.com/v1/downloads" , params = { "sessionId" : session_id}, headers = { "x-bb-api-key" : API_KEY } ) data = response.json() print ( f "Found { data[ 'total' ] } downloads" ) for download in data[ "downloads" ]: print ( f "- { download[ 'filename' ] } ( { download[ 'size' ] } bytes)" )
Filtering Options Parameter Type Description sessionIdstring Required. The session ID to list downloads for.filenamestring Filter by exact filename match. mimeTypestring Filter by MIME type (e.g., application/pdf). minSizenumber Minimum file size in bytes. maxSizenumber Maximum file size in bytes. createdAfterstring Filter downloads created after this timestamp (ISO 8601). createdBeforestring Filter downloads created before this timestamp (ISO 8601). limitnumber Maximum results to return (1-100, default: 20). offsetnumber Number of results to skip for pagination.
Example with filters: const API_KEY = process . env . BROWSERBASE_API_KEY ! ; const sessionId = "your-session-id" ; // Find PDF files larger than 1KB created in the last hour const params = new URLSearchParams ({ sessionId , mimeType: "application/pdf" , minSize: "1024" , createdAfter: new Date ( Date . now () - 60 * 60 * 1000 ). toISOString (), limit: "10" , }); const response = await fetch ( `https://api.browserbase.com/v1/downloads? ${ params } ` , { headers: { "x-bb-api-key" : API_KEY }, } ); const { downloads } = await response . json (); console . log ( `Found ${ downloads . length } matching PDFs` );
import os from datetime import datetime, timedelta import requests API_KEY = os.environ[ "BROWSERBASE_API_KEY" ] session_id = "your-session-id" # Find PDF files larger than 1KB created in the last hour response = requests.get( "https://api.browserbase.com/v1/downloads" , params = { "sessionId" : session_id, "mimeType" : "application/pdf" , "minSize" : 1024 , "createdAfter" : (datetime.now() - timedelta( hours = 1 )).isoformat(), "limit" : 10 , }, headers = { "x-bb-api-key" : API_KEY } ) downloads = response.json()[ "downloads" ] print ( f "Found { len (downloads) } matching PDFs" )
Get a Download Retrieve metadata or file content for a specific download. Use Accept: application/json for metadata, or Accept: application/octet-stream to download the file (default if no Accept header is provided).
import { writeFileSync } from "node:fs" ; const API_KEY = process . env . BROWSERBASE_API_KEY ! ; const downloadId = "download-uuid" ; // Get metadata const metadataResponse = await fetch ( `https://api.browserbase.com/v1/downloads/ ${ downloadId } ` , { headers: { "x-bb-api-key" : API_KEY , "Accept" : "application/json" , }, } ); const metadata = await metadataResponse . json (); console . log ( `File: ${ metadata . filename } ( ${ metadata . size } bytes)` ); // Download file content const fileResponse = await fetch ( `https://api.browserbase.com/v1/downloads/ ${ downloadId } ` , { headers: { "x-bb-api-key" : API_KEY , "Accept" : "application/octet-stream" , }, } ); const buffer = Buffer . from ( await fileResponse . arrayBuffer ()); writeFileSync ( metadata . filename , buffer );
import os import requests API_KEY = os.environ[ "BROWSERBASE_API_KEY" ] download_id = "download-uuid" # Get metadata metadata_response = requests.get( f "https://api.browserbase.com/v1/downloads/ { download_id } " , headers = { "x-bb-api-key" : API_KEY , "Accept" : "application/json" } ) metadata = metadata_response.json() print ( f "File: { metadata[ 'filename' ] } ( { metadata[ 'size' ] } bytes)" ) # Download file content file_response = requests.get( f "https://api.browserbase.com/v1/downloads/ { download_id } " , headers = { "x-bb-api-key" : API_KEY , "Accept" : "application/octet-stream" } ) with open (metadata[ "filename" ], "wb" ) as f: f.write(file_response.content)
Delete a Download Remove a download from storage. Returns 204 No Content on success.
const API_KEY = process . env . BROWSERBASE_API_KEY ! ; const downloadId = "download-uuid" ; const response = await fetch ( `https://api.browserbase.com/v1/downloads/ ${ downloadId } ` , { method: "DELETE" , headers: { "x-bb-api-key" : API_KEY }, } ); if ( response . status === 204 ) { console . log ( "Download deleted" ); }
import os import requests API_KEY = os.environ[ "BROWSERBASE_API_KEY" ] download_id = "download-uuid" response = requests.delete( f "https://api.browserbase.com/v1/downloads/ { download_id } " , headers = { "x-bb-api-key" : API_KEY } ) if response.status_code == 204 : print ( "Download deleted" )
Download Object Each download contains the following fields:
Field Type Description idstring Unique identifier for the download. sessionIdstring The session ID this download belongs to. filenamestring The filename of the downloaded file. mimeTypestring The MIME type of the file. sizenumber File size in bytes. checksumstring SHA256 checksum of the file. createdAtstring Timestamp when the file was downloaded (ISO 8601).
List Downloads List and filter downloads
Get Download Get metadata or file content
Delete Download Remove a download
