Browserbase Changelog

Control where your browser agents can go with Navigation Policies. Define which categories of sites to allow or block, add rules for specific domains, and reuse the same policy across sessions.

For example, a research agent can browse classified sites while blocking gambling, adult content, malware, and phishing sites. You can also choose how to handle unclassified domains. Domain overrides take priority over category rules and apply to subdomains, so you can make exceptions for sites your workflow needs.

Create a policy through the API, then pass its ID as browserSettings.riskPolicyId when starting a session. Browserbase checks page loads, iframe navigations, popups, and each redirect hop against that policy. Policy changes apply to new sessions; running sessions keep the policy they started with.

Contact support@browserbase.com to enable Navigation Policies for your project, then follow the setup guide to create your first policy.

Fetch can now reuse saved login cookies from a Browserbase Context to retrieve pages behind a login. Pass contextId to the existing Fetch endpoint and return the page as raw content, markdown, or structured JSON.

Log in through a browser session with persist: true, then end the session to save its cookies. Use that Context ID in subsequent Fetch requests to read authenticated pages without starting an interactive browser session for each request.

curl -X POST https://api.browserbase.com/v1/fetch \
  -H "Content-Type: application/json" \
  -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
  -d '{
    "url": "https://example.com/account/orders",
    "contextId": "<context-id>",
    "format": "markdown"
  }'

Authenticated Fetch uses the cookies from the last saved session and does not write updated cookies back to the Context. For pages that need JavaScript rendering or JavaScript-generated authentication tokens, use a browser session.

Learn more in our docs.

We’ve partnered with 1Password to let your agents sign in to websites securely, without ever seeing your passwords.

With our new 1Password integration, your agents can:

• Request access to a specific login when they hit a sign-in form
• Wait while you approve or deny the request from 1Password on your own device
• Have 1Password autofill and submit the credentials directly into the browser

Credentials never pass through your application, models, or logs. 1Password handles the OAuth connection, token management, and autofill inside the browser extension, and removes filled values after submission.

Browserbase sessions can be configured with zero data retention and no session recording or logging, so your agents can do real work—like logging into dashboards, SaaS tools, or test environments—while your secrets stay protected in your vault.

This release includes:

• Support for 1Password Agentic Autofill via the Browserbase extension system
• Guidance for securely storing client credentials, tokens, and integration keys on your backend

Get started today by reading our reference documentation.

We’re excited to announce Stagehand 4.3!

We’ve been working on more ways to build browser agents with your preferred models and tools, plus better control over how your workflows run. Here are the highlights:

Use Stagehand with the official OpenAI and Anthropic SDKs

Give GPT and Claude a browser through Stagehand’s toolset integrations. Build with the official model SDKs while Stagehand handles navigation, screenshots, and browser interactions. Available in TypeScript and Python, with local Chrome or Browserbase.

Get started with the OpenAI quickstart or Claude quickstart.

Here’s what else is new:

• New models without waiting for a Stagehand release — use new model IDs from supported providers including OpenAI, Anthropic, Google, Groq, and Cerebras. When your provider makes a model available, you can pass its ID directly to Stagehand without waiting for us to add it to a list. Details.
• Wait for the page to be ready — use page.waitForFunction() to wait for application state, updated text, or another browser-side condition before continuing. It supports async conditions and resumes polling after navigation while keeping the original timeout.
• More flexible remote browser connections — connect through authenticated CDP gateways using custom headers. When your application and the Stagehand extension need different routes to the same browser, configure a separate extensionCdpUrl.
• Bring the Stagehand extension to your own browser setup — getExtensionArchive() returns the bundled extension as ZIP bytes, ready to save or upload wherever you run Chrome.
• WebMCP support for newer Chromium versions — updated launch flags keep WebMCP enabled as Chromium’s feature flags change. Details.

Give it a try and tell us what you build!

We’re excited to welcome a new leading search provider to our Browserbase Search API.

Parallel comes with 2 search modes: Parallel Fast returns sub-second results when speed matters. Parallel Advanced goes deeper for multi-step research when quality matters most.

By default, any Browserbase Search request defaults to Parallel Advanced. You can switch your provider and mode at any time

import { Browserbase } from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

const response = await bb.search.web({
  query: "browserbase",
  provider: "parallel",
  mode: "fast", // enable Parallel's fast search mode
  numResults: 10,
});

console.log(`Request ID: ${response.requestId}`);
for (const result of response.results) {
  console.log(`${result.title} - ${result.url}`);
}

→ Read the docs

We're excited to announce Stagehand 4.2!

In this release, we've focused on helping browser agents update WebMCP tools as pages change, export documents programmatically, and give developers more control over how long browser operations run.

Here are the highlights:

• WebMCP tools that change with the page — subscribe to page.onToolsAdded() and page.onToolsRemoved() to react as websites expose new actions or update their forms. Useful for checkout flows where available inputs and actions change throughout the session.
• Native PDF exports — export browser pages as PDFs, with configurable print settings. Save invoices, reports, and other documents directly from your browser workflow.
• Timeouts for locator operations and snapshots — configure { timeout } on locator.click(), fill(), other locator operations, and page.snapshot(). Defaults to 20 seconds; use timeout: 0 to disable it.
• More reliable iframe and shadow DOM interactions — iframe-crossing page.locator() calls wait for the frame to be ready, page.snapshot({ includeIframes: true }) produces correct element references across frames, and XPath text() selectors correctly match direct text on pages with shadow DOM.

Give it a try and tell us what you build!

Browserbase Functions now support Secrets, so you can securely use credentials and API keys when connecting to external services.

Store a secret in Browserbase, then reference it at runtime from your Function’s ctx object without hardcoding sensitive values in your source code. This makes it safer to build Functions that authenticate with third-party APIs, databases, and other providers.

Secrets can be created and managed through the API and SDK, with CLI support for local workflows.

What you can do

• Securely store credentials in Browserbase
• Reference secrets at runtime in Functions
• Build authenticated workflows with external providers
• Keep sensitive values out of your code and logs

Learn more: ${ docs url }

defineFn("login-example", async (context) => {
  const { LOGIN_EMAIL, LOGIN_PASSWORD } = context.secrets;

  const browser = await chromium.connectOverCDP(
    context.session.connectUrl,
  );
  const browserContext = browser.contexts()[0]!;
  const page = browserContext.pages()[0] ?? await browserContext.newPage();

  await page.goto("https://your-app.example/login");
  await page.getByLabel("Email", { exact: true }).fill(LOGIN_EMAIL);
  await page.getByLabel("Password", { exact: true }).fill(LOGIN_PASSWORD);
  await page.getByRole("button", { name: "Sign in", exact: true }).click();

  return { loggedIn: true, heading, sessionId: context.session.id };
});

Agents can now pause mid-run for human-in-the-loop steps, then resume in the same session. Set a natural-language pauseWhen condition on the run; the agent gets a pause tool and enters PAUSED when that condition is met. Resume with a follow-up task.

const run = await bb.agents.runs.create({
  task: "Open the app and wait for the MFA challenge",
  pauseWhen: "an MFA or verification code is required",
});

// Later, after the user provides the code:
await bb.agents.runs.resume(run.id, {
  task: "Continue with the verification code 123456",
});

We're excited to announce Stagehand 4.1!

In this release, we've focused on providing first-class support for the Browserbase platform, namely our Fetch and Search APIs, as well as improving support for WebMCP across all websites, which helps agents interact with the web more reliably and deterministically.

Here are the highlights:

• WebMCP works better with iframes — discover and call tools inside embedded frames running in separate browser processes.
• First-party Search + Fetch tools — use browserbase.search() and browserbase.fetch() directly from Stagehand without needing to import the Browserbase SDK separately. Available in every language!
• Clearer close behavior — stagehand.close() now preserves the browser for reuse. browser.close() and browser.context.close() terminate it, regardless of keepAlive status.

Full release notes

We can't wait to see what you build!

Webhooks are now available for Browserbase Functions. Create a Webhook in the Browserbase dashboard and subscribe to events like Function pending, running, completed, and failed.

const webhook = await bb.webhooks.create({
  endpoint: "https://your.tunnel/browserbase/events",
  eventTypes: [
    "functions.invocations.completed",
    "functions.invocations.failed",
  ],
});

Search gives your agents read access to the internet, extending their context with the most up‑to‑date information.

Now, Search is natively in our dashboard, allowing you to sample queries before taking them to production.

Stagehand v4 caches act(), observe(), and extract() results on Browserbase's servers. Now you control it.

Pass cache to set a hit-count threshold - how many identical results Browserbase must see before it starts serving that result from the cache. A hit skips inference entirely: no model call, no tokens.

const stagehand = await Stagehand.create({
  browser,
  cache: { threshold: 2 }, // Serve hits after two identical results
});

// Prime this one step aggressively: the second call is a hit
await stagehand.act("click the Sign in button", {
  cache: { threshold: 1 },
});

Read the docs →

Plus:

• Every call can override the instance setting; pass cache: false to skip the cache for a single step.
• Results carry metadata.cache with a HIT / MISS / DISABLED status, a miss reason, and the tokens a hit saved.
• Model configuration stays out of the cache key, so switching models does not invalidate your cache.