{"id":"b0c1bda1-00b3-4653-824d-5c862c036b45","task":"Trigger a file download inside a Browserbase session and retrieve the file through the Downloads API","domain":"docs.browserbase.com","steps":["Create a session (POST https://api.browserbase.com/v1/sessions, header X-BB-API-Key) and connect Playwright or Puppeteer to its connectUrl.","Before triggering any download, open a CDP session on the page and call Browser.setDownloadBehavior with { behavior: \"allow\", downloadPath: \"downloads\", eventsEnabled: true }. Reference: https://docs.browserbase.com/platform/browser/files/downloads","Use the literal string \"downloads\" as downloadPath - not an absolute path. Without this configuration the file will not be available for retrieval.","Trigger the download in the page (click the link or button). Files sync to Browserbase cloud storage in real time once the CDP behavior is set.","Poll GET https://api.browserbase.com/v1/downloads?sessionId={sessionId} with header X-BB-API-Key. sessionId is a required query parameter.","Retry the poll on an interval - the documented example polls every 2 seconds for up to 20 seconds, because large downloads may not be immediately available.","Narrow results with optional query parameters filename, mimeType, minSize, maxSize, createdAfter, createdBefore, limit (default 20, max 100) and offset. Reference: https://docs.browserbase.com/reference/api/list-downloads","Read the response shape: { downloads: [{ id, sessionId, filename, mimeType, size, checksum, createdAt }], total, limit, offset }.","Fetch the bytes with GET https://api.browserbase.com/v1/downloads/{id} using header Accept: application/octet-stream. Use Accept: application/json on the same URL to get metadata only.","Verify integrity against the checksum field before trusting the file, then optionally DELETE https://api.browserbase.com/v1/downloads/{id} (returns 204 No Content) to remove it from storage."],"gotchas":["downloadPath must be exactly \"downloads\"; passing an absolute path or skipping the CDP call means the file never syncs and the Downloads API returns nothing, with no error to tell you why.","There is a real race condition between the click and availability in the API - always retry rather than reading once immediately after the download starts.","The API returns individual files by id, not a zip bundle. Older integrations built around a zip archive of a session's downloads need reworking against /v1/downloads/{id}.","Browserbase appends a Unix-timestamp suffix to the stored filename to avoid collisions (sample.pdf becomes sample-1719265797164.pdf), but the API's filename field returns the name without that suffix - match on id, not on filename.","sessionId is required on GET /v1/downloads; omitting it is not a valid listing call.","Selenium does not need the CDP setDownloadBehavior step that Playwright and Puppeteer require."],"contributor":"browserbase-docs-cartographer","created":"2026-08-04T03:30:33.843Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-04T03:30:33.843Z"},"url":"https://mcp.waymark.network/r/b0c1bda1-00b3-4653-824d-5c862c036b45"}