For the full API schema, see the Search API Reference.
Quick Start
1
Install the SDK
npm install @hyperbrowser/sdk
yarn add @hyperbrowser/sdk
pip install hyperbrowser
uv add hyperbrowser
2
Search the web
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";
config();
const client = new Hyperbrowser({
apiKey: process.env.HYPERBROWSER_API_KEY,
});
const result = await client.web.search({
query: "hyperbrowser browser automation",
});
console.log(result);
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser
load_dotenv()
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))
result = client.web.search({"query": "hyperbrowser browser automation"})
print(result)
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import WebSearchParams
load_dotenv()
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))
result = client.web.search(WebSearchParams(query="hyperbrowser browser automation"))
print(result)
curl -X POST https://api.hyperbrowser.ai/api/web/search \
-H 'Content-Type: application/json' \
-H 'x-api-key: <YOUR_API_KEY>' \
-d '{
"query": "hyperbrowser browser automation"
}'
Response
The response includes search results with titles, URLs, and snippets:{
"jobId": "962372c4-a140-400b-8c26-4ffe21d9fb9c",
"status": "completed",
"data": {
"query": "hyperbrowser browser automation",
"results": [
{
"title": "Hyperbrowser - Browser Automation Platform",
"url": "https://hyperbrowser.ai",
"description": "Hyperbrowser provides cloud browsers for AI agents and web scraping..."
},
{
"title": "Getting Started with Hyperbrowser",
"url": "https://docs.hyperbrowser.ai/quickstart",
"description": "Learn how to use Hyperbrowser for browser automation..."
}
]
}
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | The search query (max 500 characters) |
page | number | No | Page number for pagination (1-100, default: 1) |
maxAgeSeconds | number | No | Cache control—cached results older than this are treated as stale. Set to 0 to bypass cache reads. |
location | object | No | Location hint for localized search results |
filters | object | No | Advanced search filters |
Location Object
| Field | Type | Required | Description |
|---|---|---|---|
country | string | Yes | ISO-2 country code (e.g., "US", "GB", "DE") |
state | string | No | State code (for supported countries) |
city | string | No | City name (max 200 characters) |
Filters Object
| Field | Type | Description |
|---|---|---|
exactPhrase | boolean | Wrap query in quotes for exact match |
semanticPhrase | boolean | Use semantic search |
excludeTerms | string[] | Terms to exclude from results |
boostTerms | string[] | Terms to prioritize in results |
filetype | string | Filter by file type: pdf, doc, docx, xls, xlsx, ppt, pptx, html |
site | string | Limit results to a specific site |
excludeSite | string | Exclude results from a specific site |
intitle | string | Search term must appear in page title |
inurl | string | Search term must appear in URL |
exactPhrase and semanticPhrase cannot both be true.Example with filters
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";
config();
const client = new Hyperbrowser({
apiKey: process.env.HYPERBROWSER_API_KEY,
});
const result = await client.web.search({
query: "machine learning tutorials",
page: 1,
location: {
country: "US",
},
filters: {
excludeTerms: ["beginner"],
filetype: "pdf",
site: "arxiv.org",
},
});
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser
load_dotenv()
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))
result = client.web.search(
{
"query": "machine learning tutorials",
"page": 1,
"location": {"country": "US"},
"filters": {
"exclude_terms": ["beginner"],
"filetype": "pdf",
"site": "arxiv.org",
},
}
)
print(result)
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import WebSearchParams, WebSearchLocation, WebSearchFilters
load_dotenv()
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))
result = client.web.search(
WebSearchParams(
query="machine learning tutorials",
page=1,
location=WebSearchLocation(country="US"),
filters=WebSearchFilters(
exclude_terms=["beginner"],
filetype="pdf",
site="arxiv.org",
),
)
)
print(result)
curl -X POST https://api.hyperbrowser.ai/api/web/search \
-H 'Content-Type: application/json' \
-H 'x-api-key: <YOUR_API_KEY>' \
-d '{
"query": "machine learning tutorials",
"page": 1,
"location": {
"country": "US"
},
"filters": {
"excludeTerms": ["beginner"],
"filetype": "pdf",
"site": "arxiv.org"
}
}'