Search - Browserbase Documentation

The Browserbase Search API gives your agents fast, token-efficient web search results as a complement to browser sessions. Use it for recon, lead discovery, or RAG pipelines, then hand off to a browser session for interaction.

Perform a search

Send a POST request to /v1/search with your query. Authenticate with the same x-bb-api-key header used across the Browserbase API.

Node.js
Python
cURL

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

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

const response = await bb.search.web({
  query: "browserbase",
  numResults: 10, // up to 25 results
});

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

const response = await fetch("https://api.browserbase.com/v1/search", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-bb-api-key": process.env.BROWSERBASE_API_KEY!,
  },
  body: JSON.stringify({
    query: "browserbase",
    numResults: 10,
  }),
});

const data = await response.json();

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

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

response = bb.search.web(
    query="browserbase",
    num_results=5,
)

print(f"Request ID: {response.request_id}")
for result in response.results:
    print(f"{result.title} - {result.url}")

import requests
import os

response = requests.post(
    "https://api.browserbase.com/v1/search",
    headers={
        "Content-Type": "application/json",
        "x-bb-api-key": os.environ["BROWSERBASE_API_KEY"],
    },
    json={
        "query": "browserbase",
        "numResults": 10,
    },
)

data = response.json()

print(f"Request ID: {data['requestId']}")
for result in data["results"]:
    print(f"{result['title']} - {result['url']}")

curl -X POST https://api.browserbase.com/v1/search \
  -H "Content-Type: application/json" \
  -H "x-bb-api-key: $BROWSERBASE_API_KEY" \
  -d '{
    "query": "browserbase",
    "numResults": 10
  }'

Request parameters

Parameter	Type	Required	Description
`query`	string	Yes	The search query (1–200 characters)
`numResults`	integer	No	Number of results to return (1–25, default: 10)

Response

Field	Type	Description
`requestId`	string	Unique identifier for the request
`query`	string	The search query that was executed
`results`	array	List of search result objects

Each result object contains:

Field	Type	Always present	Description
`id`	string	Yes	Unique identifier for the result
`url`	string	Yes	URL of the search result
`title`	string	Yes	Title of the search result
`author`	string	No	Author of the content
`publishedDate`	string	No	Publication date (ISO 8601)
`image`	string	No	Image URL
`favicon`	string	No	Favicon URL

Combining search with browser sessions

A common pattern is using the Search API to find relevant URLs, then opening them in browser sessions for deeper interaction, such as extracting content, filling forms, or taking screenshots.

Node.js
Python

import { Browserbase } from "@browserbasehq/sdk";
import { chromium } from "playwright-core";

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

const searchResponse = await bb.search.web({
  query: "browserbase documentation",
  numResults: 10,
});

for (const result of searchResponse.results) {
  const session = await bb.sessions.create();
  const browser = await chromium.connectOverCDP(session.connectUrl);
  const page = browser.contexts()[0].pages()[0];

  await page.goto(result.url);
  const content = await page.textContent("body");
  console.log(`Content from ${result.title}:`, content?.slice(0, 200));

  await page.close();
  await browser.close();
}

from browserbase import Browserbase
from playwright.sync_api import sync_playwright
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

search_response = bb.search.web(
    query="browserbase documentation",
    num_results=3,
)

with sync_playwright() as playwright:
    for result in search_response.results:
        session = bb.sessions.create()
        browser = playwright.chromium.connect_over_cdp(session.connect_url)
        page = browser.contexts[0].pages[0]

        page.goto(result.url)
        content = page.text_content("body")
        print(f"Content from {result.title}:", content[:200] if content else "")

        page.close()
        browser.close()

Rate limits

The Search API is rate limited to 120 requests per minute per project. Exceeding this returns a 429 status code.

For high-volume use cases, space out your requests or implement exponential backoff in your retry logic.

Error handling

Status Code	Meaning
`200`	Success
`400`	Invalid request (empty query, `numResults` out of range)
`403`	Search API not enabled for your project
`429`	Rate limit exceeded
`503`	Search service temporarily unavailable
`500`	Internal server error

Node.js
Python

SDK

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

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

try {
  const response = await bb.search.web({ query: "browserbase" });
  console.log(response.results);
} catch (error) {
  if (error.status === 429) {
    console.log("Rate limited: retrying after delay");
  } else if (error.status === 503) {
    console.log("Service temporarily unavailable: retrying");
  } else {
    console.error("Search failed:", error);
  }
}

SDK

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

try:
    response = bb.search.web(query="browserbase")
    print(response.results)
except Exception as error:
    print(f"Search failed: {error}")

When to use Search

Use Search when your browser agent doesn’t yet know where the information lives. In other words, it will give you the best starting points on the web for some task. Think about Search -> Fetch -> Browsers

Search: Find relevant sources (website, news, docs).
Fetch: Quickly extract content from most pages, and filter out low-value results.
Browsers: Log in to portals with agent identity, navigate complex pages, and extract the hard-to-reach data.

Need more help deciding which API?

Read our full guide breaking down which API to use with examples.

​Perform a search

​Request parameters

​Response

​Combining search with browser sessions

​Rate limits

​Error handling

​When to use Search

Need more help deciding which API?

Perform a search

Request parameters

Response

Combining search with browser sessions

Rate limits

Error handling

When to use Search