Skip to main content
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. 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: Sign in to websites, navigate complex pages, and extract the hard-to-reach data.
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
For every request parameter and response field, see the Web Search API reference.

Providers and modes

provider picks the search provider that serves a request, and mode picks one of that provider’s modes. Both are optional. If you omit provider, Browserbase uses parallel. Set provider whenever you set mode. Every plan’s included monthly searches are shared across providers and modes. Exa deep-lite and deep searches are not part of the included searches. If you omit provider and parallel can’t apply one of your parameters, Browserbase sends the request to a provider that can. The provider and mode fields in the response show which provider served the request, and the price follows that provider and mode. If you set provider, a parameter it can’t apply returns a 400.
Node.js

Filter results

Add parameters to the request body to narrow and shape the results. This request returns results from two domains published after a date, with the most relevant passages of each page:
cURL

Provider support

Provider limits

When provider is parallel:
  • Set includeDomains or excludeDomains, not both.
  • Use up to 200 domains in total.
  • Don’t include a scheme (https://), port, query string, or fragment in a domain.
  • startPublishedDate applies by day. A time after midnight UTC moves the start to the next day.
  • userLocation accepts only the supported countries.

Category limits

Some categories don’t accept all filters. These requests return a 400:
  • company with startPublishedDate or endPublishedDate
  • people with startPublishedDate, endPublishedDate, or excludeDomains

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 Playwright

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

Node.js

Appendix: supported countries

When provider is parallel, userLocation accepts only these country codes. Other providers accept any two-letter ISO 3166-1 code. Codes aren’t case-sensitive.

Need more help deciding which API?

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

Fetch

Retrieve web content for your application.