Search

Search queries the web and returns structured results—titles, URLs, and snippets—ready to use in your application. Combine it with Fetch to retrieve full page content from search results.

For the full API schema, see the Search API Reference.

Quick Start

Install the SDK

npm install @hyperbrowser/sdk

yarn add @hyperbrowser/sdk

pip install hyperbrowser

uv add hyperbrowser

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"
    }
  }'

X402 Support

For agentic workflows, Hyperbrowser supports x402 payment for the Search API, enabling agents to programmatically pay for individual Search requests at request time using USDC, with payment handled inline via HTTP 402 responses. See the X402 Search guide page for details. Each request returns search results. To purchase a browser you can control directly, use Sessions with X402.

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Integrations

Quick Start

Response

Parameters

Location Object

Filters Object

Example with filters

X402 Support

​Quick Start

​Response

​Parameters

​Location Object

​Filters Object

​Example with filters

​X402 Support

Quick Start

Response

Parameters

Location Object

Filters Object

Example with filters

X402 Support