> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Fast, token-efficient web search results as a complement to browser sessions.

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](/platform/browser/getting-started/create-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.

<Tabs>
  <Tab title="Node.js">
    <CodeGroup>
      ```typescript SDK theme={null}
      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}`);
      }
      ```

      ```typescript REST theme={null}
      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}`);
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Python">
    <CodeGroup>
      ```python SDK theme={null}
      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}")
      ```

      ```python REST theme={null}
      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']}")
      ```
    </CodeGroup>
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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
      }'
    ```
  </Tab>
</Tabs>

### 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 — extracting content, filling forms, or taking screenshots.

<Tabs>
  <Tab title="Node.js">
    <CodeGroup>
      ```typescript Playwright theme={null}
      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();
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Python">
    <CodeGroup>
      ```python Playwright theme={null}
      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()
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Rate limits

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

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

## 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                                    |

<Tabs>
  <Tab title="Node.js">
    ```typescript SDK theme={null}
    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);
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python SDK theme={null}
    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}")
    ```
  </Tab>
</Tabs>