Python SDK
All the features fast Python development with Browserbase.
If you are working with Python, the official browserbase package is the easiest way to connect and act upon headless browsers running on Browserbase.
Basic usage
The browserbase SDK makes it easy to load pages and take screenshots:
from browserbase import Browserbase
# Init the SDK with `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
# environment variables
browserbase = Browserbase()
# Load a webpage
result = browserbase.load("https://example.com")
# Load multiple webpages (returns iterator)
result = browserbase.load(["https://example.com"])
# Text-only mode
result = browserbase.load("https://example.com", text_content=True)
# Screenshot (returns bytes)
result = browserbase.screenshot("https://example.com", full_page=True)
Installation
You can install browserbase using pip:
pip install browserbase
Configuration
Create a Browserbase client as follows:
from browserbase import Browserbase
# Init the SDK with `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
# environment variables
browserbase = Browserbase()
# Init the SDK the `api_key` and `project_id` params
browserbase = Browserbase('<API_KEY>', '<PROJECT_ID>')
Parameters
Your Browserbase API Key.
If missing, will be loaded from os.environ["BROWSERBASE_API_KEY"].
Your Browserbase Project ID.
If missing, will be loaded from os.environ["BROWSERBASE_PROJECT_ID"].
Load pages and take screenshots
load(url_or_urls, text_content=)
Return the text or raw HTML from the given URL(s).
from browserbase import Browserbase
# Init the SDK
browserbase = Browserbase()
# Load a webpage
result = browserbase.load("https://example.com")
# Load multiple webpages (returns iterator)
result = browserbase.load(["https://example.com"])
# Text-only mode
result = browserbase.load("https://example.com", text_content=True)
Parameters
A valid URL or array of URLs.
Return text only or raw HTML.
screenshot(url, full_page=)
Return a screenshot as bytes.
from browserbase import Browserbase
# Init the SDK
browserbase = Browserbase()
# Screenshot (returns bytes)
result = browserbase.screenshot("https://example.com", full_page=True)
Parameters
A valid URL.
Set to true to take a full-page screenshot.
Return type
More information on how to deal with bytes
here.
Connect with Playwright
get_connect_url(session_id, proxy)
Returns a Connect API URL for Playwright.
from browserbase import Browserbase
from playwright.sync_api import sync_playwright, Playwright
def run(playwright: Playwright):
browserbase = Browserbase()
chromium = playwright.chromium
browser = chromium.connect_over_cdp(browserbase.get_connect_url())
# ...
with sync_playwright() as playwright:
run(playwright)
Parameters
A valid Session ID.
Enables Proxying.
Sessions, downloads and recordings
create_session(options)
Create a new Session.
from browserbase import Browserbase, CreateSessionOptions
browserbase = Browserbase()
options = CreateSessionOptions(extensionId='123')
browserbase.create_session(options)
Parameters
options parameter is optional.A valid Project ID.
A valid Extension ID.
Return type
The returned Session type matches the Sessions API GET /v1/sessions/:id
endpoint response type.
get_session(session_id)
Retrieve a Session.
from browserbase import Browserbase
browserbase = Browserbase()
session = browserbase.get_session("fef4db93-9995-4147-be1c-27ebb0228ea6")
Parameters
A valid Session ID.
Return type
The returned Session object matches the Sessions API GET /v1/sessions/:id
endpoint response type.
list_sessions()
Returns the list of Sessions.
from browserbase import Browserbase
browserbase = Browserbase()
sessions = browserbase.list_sessions()
for i, session in sessions
# ...
Return type
The returned Session list matches the Sessions API GET /v1/sessions
endpoint response type.
get_session_downloads(session_id, retry_interval, retry_count)
Retrieve and save a Session’s downloads on disk.
from browserbase import Browserbase
browserbase = Browserbase()
session = browserbase.create_session()
# ...
browserbase.get_session_downloads(session.id)
During a Session, files are sync in real time; the size of your downloads might
affect their immediate availability through the /downloads endpoint.
The get_session_downloads() method provides a retry mechanism to cope with this
use case.
Parameters
A valid Session ID.
The time between each retry.
The number of retries.
Return type
Returns the file as bytes.
More information on how to deal with bytes
here.
get_debug_connection_urls(session_id)
Retrieve the Session Live View URLs.
from browserbase import Browserbase
import os
# Init the SDK with `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
# environment variables
api_key = os.environ['BROWSERBASE_API_KEY']
project_id = os.environ['BROWSERBASE_PROJECT_ID']
# Instance the SDK and create a browser session.
browserbase = Browserbase(api_key, project_id)
session = browserbase.create_session()
# Return the debug (Session Live View) URL. If the session is
# multitab, it returns the debug URL for the first page only.
debug_urls = browserbase.get_debug_connection_urls(session.id)
print(f"Debug URL: {debug_urls.debuggerUrl}")
Parameters
A valid Session ID.
Return type
An object with the following properties is returned:
The URL to access the fullScreen remote view of the Session.
The URL to access the visible viewport remote view of the Session.
The WebSocket URL for the Session.
get_session_recording(session_id)
Retrieve the Session Recordings, a collection of rrweb events like DOM changes and user actions.
from browserbase import Browserbase
browserbase = Browserbase()
EventType = {
"IncrementalSnapshot": "IncrementalSnapshot"
}
IncrementalSource = {
"Input": "Input",
"MouseInteraction": "MouseInteraction",
"MouseMove": "MouseMove"
}
browserbase = Browserbase()
events = await browserbase.get_session_recording("fef4db93-9995-4147-be1c-27ebb0228ea6")
for event in events:
if event.get("type") == EventType["IncrementalSnapshot"] and event.get("data"):
if event["data"].get("source") in {IncrementalSource["Input"], IncrementalSource["MouseInteraction"], IncrementalSource["MouseMove"]}:
# ...
pass
Parameters
A valid Session ID.
Return type
Find a complete example in our “Use the Session recordings API” guide.
Was this page helpful?