Setting the file. One moment.
Subchapter 16.3
REFERENCE.mdMarkdown4 KBView on GitHub
POST https://api.browserbase.com/v1/searchSearch the web and return structured results with titles, URLs, and metadata.
All requests require the X-BB-API-Key header:
curl -X POST "https://api.browserbase.com/v1/search" \
-H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "example search"}'Get your API key from https://browserbase.com/settings (opens in a new tab).
Content-Type: application/json
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | — | The search query |
numResults | integer | No | 10 | Number of results to return (1-25) |
curl -X POST "https://api.browserbase.com/v1/search" \
-H "Content-Type: application/json" \
-H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
-d '{"query": "browser automation"}'curl -X POST "https://api.browserbase.com/v1/search" \
-H "Content-Type: application/json" \
-H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
-d '{
"query": "browser automation",
"numResults": 5
}'Successful search. Returns:
| Field | Type | Description |
|---|---|---|
requestId | string | Unique identifier for the search request |
query | string | The search query that was executed |
results | array | List of search result objects |
Each result object:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the result |
url | string | URL of the result |
title | string | Title of the result |
author | string? | Author of the content (if available) |
publishedDate | string? | Publication date (if available) |
image | string? | Image URL (if available) |
favicon | string? | Favicon URL (if available) |
Example response:
{
"requestId": "req_abc123",
"query": "browser automation",
"results": [
{
"id": "res_1",
"url": "https://example.com/browser-automation-guide",
"title": "Complete Guide to Browser Automation",
"author": "Jane Doe",
"publishedDate": "2025-12-01",
"image": "https://example.com/images/guide.png",
"favicon": "https://example.com/favicon.ico"
},
{
"id": "res_2",
"url": "https://example.com/headless-browsers",
"title": "Headless Browser Comparison",
"author": null,
"publishedDate": null,
"image": null,
"favicon": "https://example.com/favicon.ico"
}
]
}Invalid request body. Check that query is a non-empty string and numResults is between 1 and 25.
{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid query"
}Fix: Ensure the query field is provided and is a non-empty string.
Invalid or missing API key.
{
"statusCode": 403,
"error": "Forbidden",
"message": "Invalid API key"
}Fix: Check that BROWSERBASE_API_KEY is set correctly. Get your key from https://browserbase.com/settings (opens in a new tab).
Rate limit exceeded. Wait and retry.
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "Rate limit exceeded"
}Fix: Reduce request frequency or contact support for higher limits.
Unexpected server error.
{
"statusCode": 500,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}Fix: Retry the request. If the error persists, contact support.
| Variable | Required | Description |
|---|---|---|
BROWSERBASE_API_KEY | Yes | API key from https://browserbase.com/settings (opens in a new tab) |
Search requests are rate-limited per account. If you hit 429 errors, reduce request frequency or contact support for higher limits.
The @browserbasehq/sdk does not yet include a search method. Use cURL or direct HTTP calls with the X-BB-API-Key header for now.