Search

What is `search()`?

An agent that doesn’t know where to start has to launch a browser, load a search engine, wait for the page, and read a result list before it can do anything useful. browserbase.search() collapses that into a single API call: you send a query, you get back ranked results with URLs, titles, and metadata.

TypeScript
Python
Go

import { browserbase } from "@browserbasehq/stagehand";

const searchResult = await browserbase.search({
  apiKey: process.env.BROWSERBASE_API_KEY,
  query: "browser agent frameworks",
  numResults: 5,
});

for (const result of searchResult.results) {
  console.log(`${result.title}: ${result.url}`);
}

import os

from stagehand import browserbase

search_result = await browserbase.search(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    query="browser agent frameworks",
    num_results=5,
)

for result in search_result.results:
    print(f"{result.title}: {result.url}")

numResults := 5

searchResult, err := stagehand.SearchBrowserbase(ctx, stagehand.BrowserbaseSearchOptions{
	APIKey:     os.Getenv("BROWSERBASE_API_KEY"),
	Query:      "browser agent frameworks",
	NumResults: &numResults,
})
if err != nil {
	return err
}

for _, result := range searchResult.Results {
	fmt.Printf("%s: %s\n", result.Title, result.URL)
}

search() is a Browserbase cloud feature. The query runs on Browserbase infrastructure and needs a Browserbase API key, so local browsers have no equivalent.

Why use `search()`?

Whole-web index

Search spans the whole web, so your agent can discover sources on any topic instead of being limited to domains you hardcoded.

Structured, ranked output

Results come back as structured objects, ranked for relevance and ready for the agent to act on, with no result page to parse.

Live, low-latency results

Every query hits the live web rather than a cached index, and it returns without the cost of booting a browser and rendering a search page.

Token-optimized

Each result carries the URL, title, and metadata rather than full page excerpts. The agent decides which pages are worth fetching, and the context window stays lean.

Setup

search() ships with the Stagehand SDK. The only requirement is a Browserbase API key:

export BROWSERBASE_API_KEY="bb_live_..."

TypeScript
Python
Go

import "dotenv/config";
import { browserbase } from "@browserbasehq/stagehand";

const searchResult = await browserbase.search({
  apiKey: process.env.BROWSERBASE_API_KEY,
  query: "stagehand browser automation",
});

console.log(searchResult.requestId, searchResult.results.length);

import asyncio
import os

from stagehand import browserbase


async def main() -> None:
    search_result = await browserbase.search(
        api_key=os.environ["BROWSERBASE_API_KEY"],
        query="stagehand browser automation",
    )
    print(search_result.request_id, len(search_result.results))


if __name__ == "__main__":
    asyncio.run(main())

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"

	stagehand "github.com/browserbase/stagehand/packages/sdk-go/v4"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	apiKey := os.Getenv("BROWSERBASE_API_KEY")
	if apiKey == "" {
		return errors.New("BROWSERBASE_API_KEY is required")
	}

	searchResult, err := stagehand.SearchBrowserbase(ctx, stagehand.BrowserbaseSearchOptions{
		APIKey: apiKey,
		Query:  "stagehand browser automation",
	})
	if err != nil {
		return err
	}

	fmt.Println(searchResult.RequestID, len(searchResult.Results))
	return nil
}

Response

A search returns the query it ran, a request ID you can quote in support requests, and the ranked results. id, title, and url are always present; the rest are filled in when the source exposes them.

{
  "query": "browser agent frameworks",
  "requestId": "req_01JB8Z3K7Q2M4N",
  "results": [
    {
      "id": "https://docs.stagehand.dev/v4/first-steps/introduction",
      "title": "Introduction - Stagehand",
      "url": "https://docs.stagehand.dev/v4/first-steps/introduction",
      "author": null,
      "favicon": "https://docs.stagehand.dev/favicon.ico",
      "image": null,
      "publishedDate": "2025-11-04T00:00:00.000Z"
    }
  ]
}

Field names follow each language’s conventions: requestId and publishedDate in TypeScript, request_id and published_date in Python, and RequestID and PublishedDate on the Go structs.

API reference

Parameters

string

required

Your Browserbase API key. Search is billed to the project that owns the key.

string

required

The search query, 1–200 characters.

number

How many results to return, between 1 and 25. Defaults to 10.

string

Browserbase API origin override. Defaults to https://api.browserbase.com.

Returns

string

The query that was executed.

string

Identifier for this search request.

SearchResult[]

Results ordered by relevance.

Show SearchResult

string

Stable identifier for the result.

string

Page title.

string

Canonical URL of the page. Pass it straight to fetch() or page.goto().

string | null

Author, when the source declares one.

string | null

Favicon URL, when available.

string | null

Representative image URL, when available.

string | null

ISO 8601 publication date, when available.

Stagehand rejects invalid input before the request leaves your process: an empty query, a query over 200 characters, or a numResults outside 1–25 raises locally rather than costing you a round trip.

Search, then read

search() deliberately returns pointers rather than page bodies. Pair it with fetch() to pull the content of the one or two pages that matter, and reach for a full browser session only when the page needs interaction.

TypeScript
Python
Go

const { results } = await browserbase.search({
  apiKey: process.env.BROWSERBASE_API_KEY,
  query: "browser agent frameworks",
  numResults: 5,
});

const page = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  url: results[0].url,
  format: "markdown",
});

console.log(page.content);

search_result = await browserbase.search(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    query="browser agent frameworks",
    num_results=5,
)

fetched = await browserbase.fetch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    url=search_result.results[0].url,
    format="markdown",
)

print(fetched.content)

numResults := 5
searchResult, err := stagehand.SearchBrowserbase(ctx, stagehand.BrowserbaseSearchOptions{
	APIKey:     os.Getenv("BROWSERBASE_API_KEY"),
	Query:      "browser agent frameworks",
	NumResults: &numResults,
})
if err != nil {
	return err
}
if len(searchResult.Results) == 0 {
	return errors.New("search returned no results")
}

fetched, err := stagehand.FetchBrowserbase(ctx, stagehand.BrowserbaseFetchOptions{
	APIKey: os.Getenv("BROWSERBASE_API_KEY"),
	URL:    searchResult.Results[0].URL,
	Format: stagehand.BrowserbaseFetchFormatMarkdown,
})
if err != nil {
	return err
}

content, ok := fetched.Content.AsString()
if !ok {
	return errors.New("fetch returned non-string content")
}
fmt.Println(content)

Use cases

General agents and chatbots

Retrieve up-to-date information to produce more accurate answers.

Coding agents

Find the best library, or the documentation page for a given technical requirement.

Research agents

Conduct in-depth web research across the whole web.

Voice agents

Find relevant sources fast enough for low-latency voice interactions.

Limits

Limit	Value
Query length	1–200 characters
Results per query	1–25 (default 10)
Rate limit	120 requests per minute, per project

Exceeding the rate limit returns a 429. Back off and retry rather than looping.

First steps

The basics

Configuration

Add-ons

Integrations

Best practices

Cookbooks

Migration guide

SDK reference

What is `search()`?

Why use `search()`?

Whole-web index

Structured, ranked output

Live, low-latency results

Token-optimized

Setup

Response

API reference

Parameters

Returns

Search, then read

Use cases

General agents and chatbots

Coding agents

Research agents

Voice agents

Limits

Next steps

Web Fetch

Browserbase Search

​What is search()?

​Why use search()?

Whole-web index

Structured, ranked output

Live, low-latency results

Token-optimized

​Setup

​Response

​API reference

​Parameters

​Returns

​Search, then read

​Use cases

General agents and chatbots

Coding agents

Research agents

Voice agents

​Limits

​Next steps

Web Fetch

Browserbase Search

What is `search()`?

Why use `search()`?

Setup

Response

API reference

Parameters

Returns

Search, then read

Use cases

Limits

Next steps