Node.js SDK
All the features and utilities for fast Node.js development with Browserbase.
If you are working with Node.js, the official @browserbasehq/sdk
package is the easiest way
to connect and act upon headless browsers running on Browserbase.
Basic usage
Here is an example using the Browserbase Node.js SDK to load and screenshot pages:
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK with `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
// environment variables
const browserbase = new Browserbase();
// Load a webpage
const rawHtml = await browserbase.load("https://www.browserbase.com");
// Text-only mode
const text = await browserbase.load("https://www.browserbase.com", {
textContent: true,
});
// Screenshot (returns bytes)
const result = await browserbase.screenshot("https://www.browserbase.com", {
textContent: true,
});
Installation
Configuration
Create a Browserbase client instance:
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK with `BROWSERBASE_API_KEY` and `BROWSERBASE_PROJECT_ID`
// environment variables
const browserbase = new Browserbase();
// Init the SDK with the `apiKey` and `projectId` options
const browserbase = new Browserbase({ apiKey: "xxx", projectId: "xxx" });
Parameters
options
parameter is optional.Your Browserbase API Key.
If missing, will be loaded from process.env.BROWSERBASE_API_KEY
.
Your Browserbase Project ID.
If missing, will be loaded from process.env.BROWSERBASE_PROJECT_ID
.
A customSessions API Base URL.
A custom Connect API Base URL.
Load pages and take screenshots
load(url_or_urls, options)
Return the text or raw HTML from the given URL(s).
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK
const browserbase = new Browserbase();
// Load a webpage
const rawHtml = await browserbase.load("https://www.browserbase.com");
// Load multiple webpages (returns iterator)
const rawHtmls = browserbase.load([
"https://www.browserbase.com",
"https://docs.browserbase.com",
]);
for await (let rawHtml of rawHtmls) {
// ...
}
// Text-only mode
const text = await browserbase.load("https://www.browserbase.com", {
textContent: true,
});
Parameters
A valid URL or array of URLs.
options
parameter is optional.Return text only or raw HTML.
A valid Session ID.
Enables Proxying.
Return type
If url
is a string
, a Promise<string>
is returned.
If url
is a
string[]
, a Generator
is returned.
screenshot(url, options)
Return the Blob
of a screenshot.
import { Browserbase } from "@browserbasehq/sdk";
// Init the SDK
const browserbase = new Browserbase();
const blob = await browserbase.screenshot("https://www.browserbase.com");
// Full page screenshot
const blob2 = await browserbase.screenshot("https://www.browserbase.com", {
fullPage: true,
});
Parameters
A valid URL.
options
parameter is optional.Set to true
to take a full-page screenshot.
A valid Session ID.
Enables Proxying.
Return type
More information on how to deal with Blob
here.
Connect with Playwright or Puppeteer
getConnectURL(options)
Returns a Connect API URL for Puppeteer or Playwright.
Parameters
options
parameter is optional.A valid Session ID.
Enables Proxying.
Sessions, downloads and recordings
createSession(options)
Create a new Session.
import { Browserbase } from "@browserbasehq/sdk";
const browserbase = new Browserbase();
const { id: sessionId } = await browserbase.createSession({
browserSettings: {
fingerprint: { devices: ["mobile"] },
},
});
Parameters
options
parameter is optional.A valid Project ID.
A valid Extension ID.
Return type
The returned Session
object matches the Sessions API GET /v1/sessions/:id
endpoint response type.
getSession(sessionId)
Retrieve a Session.
import { Browserbase } from "@browserbasehq/sdk";
const browserbase = new Browserbase();
const { status } = await browserbase.getSession(
"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.
listSessions()
Returns the list of Sessions.
import { Browserbase } from "@browserbasehq/sdk";
const browserbase = new Browserbase();
const sessions = await browserbase.listSessions();
Return type
The returned Session
list matches the Sessions API GET /v1/sessions
endpoint response type.
getSessionDownloads(sessionId, filePath, retryInterval, retryCount)
Retrieve and save a Session’s downloads on disk.
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";
const browserbase = new Browserbase();
const { id: sessionId } = await browserbase.createSession();
const browser = await chromium.connectOverCDP(
browserbase.connectUrl({ sessionId }),
);
// ...navigate the page and take actions...
await browserbase.getSessionDownloads(sessionId, "downloads.zip");
During a Session, files are synced in real time; the size of your downloads might
affect their immediate availability through the /downloads
endpoint.
The getSessionDownloads()
method provides a retry mechanism to cope with this
use case.
Parameters
A valid Session ID.
A valid relative file path.
The time between each retry.
The number of retries.
getDebugConnectionURLs(sessionId)
Retrieve the Session Live View URLs.
import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";
const browserbase = new Browserbase();
const { id: sessionId } = await browserbase.createSession();
const browser = await chromium.connectOverCDP(
browserbase.connectUrl({ sessionId }),
);
// ...navigate the page and take actions...
const { debuggerFullscreenUrl } =
await browserbase.getDebugConnectionURLs(sessionId);
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.
getSessionRecording(sessionId)
Retrieve the Session Recordings, a collection of rrweb events like DOM changes and user actions.
import { Browserbase, SessionRecording } from "@browserbasehq/sdk";
import { EventType, IncrementalSource } from "@rrweb/types";
const browserbase = new Browserbase();
const events = await browserbase.getSessionRecording(
"fef4db93-9995-4147-be1c-27ebb0228ea6",
);
for (let event of events) {
if (
event.type &&
event.type === EventType.IncrementalSnapshot &&
event.data
) {
// Filter input and mouse interactions
if (
[
IncrementalSource.Input,
IncrementalSource.MouseInteraction,
IncrementalSource.MouseMove,
].includes(event.data.source)
) {
// ...
}
}
}
Parameters
A valid Session ID.
Return type
Find a complete example in our “Use the Session recordings API” guide.
Was this page helpful?