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.
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 |
|---|
sessionId | string | Required. The session ID to list downloads for. |
filename | string | Filter by exact filename match. |
mimeType | string | Filter by MIME type (e.g., application/pdf). |
minSize | number | Minimum file size in bytes. |
maxSize | number | Maximum file size in bytes. |
createdAfter | string | Filter downloads created after this timestamp (ISO 8601). |
createdBefore | string | Filter downloads created before this timestamp (ISO 8601). |
limit | number | Maximum results to return (1-100, default: 20). |
offset | number | Number of results to skip for pagination. |
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 |
|---|
id | string | Unique identifier for the download. |
sessionId | string | The session ID this download belongs to. |
filename | string | The filename of the downloaded file. |
mimeType | string | The MIME type of the file. |
size | number | File size in bytes. |
checksum | string | SHA256 checksum of the file. |
createdAt | string | Timestamp when the file was downloaded (ISO 8601). |
