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

The options parameter is optional.
options.apiKey
string

Your Browserbase API Key.

If missing, will be loaded from process.env.BROWSERBASE_API_KEY.

options.projectId
string

Your Browserbase Project ID.

If missing, will be loaded from process.env.BROWSERBASE_PROJECT_ID.

options.baseURL
string
default: "https://www.browserbase.com"

A customSessions API Base URL.

options.baseConnectURL
string
default: "wss://connect.browserbase.com"

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

url_or_urls
string | string[]
required

A valid URL or array of URLs.

options
object
The options parameter is optional.
options.textContent
boolean
default: false

Return text only or raw HTML.

options.sessionId
string

A valid Session ID.

options.proxy
boolean
default: false

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

url
string
required

A valid URL.

options
object
The options parameter is optional.
options.fullPage
boolean
default: false

Set to true to take a full-page screenshot.

options.sessionId
string

A valid Session ID.

options.proxy
boolean
default: false

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
object
The options parameter is optional.
options.sessionId
string

A valid Session ID.

options.proxy
boolean
default: false

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
object
The options parameter is optional.
options.projectId
string

A valid Project ID.

options.extensionId
string

A valid Extension ID.

options.fingerprint
object

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

sessionId
string
required

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

sessionId
string
required

A valid Session ID.

filePath
string
required

A valid relative file path.

retryInterval
number
default: 2000

The time between each retry.

retryCount
number
default: 2

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

sessionId
string
required

A valid Session ID.

Return type

An object with the following properties is returned:

debuggerFullscreenUrl
string
required

The URL to access the fullScreen remote view of the Session.

debuggerUrl
string
required

The URL to access the visible viewport remote view of the Session.

wsUrl
string
required

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

sessionId
string
required

A valid Session ID.

Return type

Find a complete example in our “Use the Session recordings API” guide.