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: Sign in to websites, navigate complex pages, and extract the hard-to-reach data.
Perform a search
Send aPOST 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
Node.js
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
- Python
- cURL
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
Whenprovider is parallel:
- Set
includeDomainsorexcludeDomains, not both. - Use up to 200 domains in total.
- Don’t include a scheme (
https://), port, query string, or fragment in a domain. startPublishedDateapplies by day. A time after midnight UTC moves the start to the next day.userLocationaccepts only the supported countries.
Category limits
Some categories don’t accept all filters. These requests return a400:
companywithstartPublishedDateorendPublishedDatepeoplewithstartPublishedDate,endPublishedDate, orexcludeDomains
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
Node.js Playwright
Rate limits
The Search API is rate limited to 120 requests per minute per project. Exceeding this returns a429 status code.
Error handling
- Node.js
- Python
Node.js
Appendix: supported countries
Whenprovider is parallel, userLocation accepts only these country codes. Other providers accept any two-letter ISO 3166-1 code. Codes aren’t case-sensitive.
Show supported countries
Show supported countries
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.