> ## Documentation Index
> Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Query the web and get clean, structured results

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

<Info>
  For the full API schema, see the [Search API Reference](/api-reference/search-the-web).
</Info>

***

## Quick Start

<Steps>
  <Step title="Install the SDK">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @hyperbrowser/sdk
      ```

      ```bash yarn theme={null}
      yarn add @hyperbrowser/sdk
      ```

      ```bash pip theme={null}
      pip install hyperbrowser
      ```

      ```bash uv theme={null}
      uv add hyperbrowser
      ```
    </CodeGroup>
  </Step>

  <Step title="Search the web">
    <CodeGroup>
      ```typescript Node theme={null}
      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);
      ```

      ```python Python theme={null}
      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)
      ```

      ```bash cURL theme={null}
      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"
        }'
      ```
    </CodeGroup>
  </Step>
</Steps>

***

## Response

The response includes search results with titles, URLs, and snippets:

```json theme={null}
{
  "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                                                  |

<Warning>
  `exactPhrase` and `semanticPhrase` cannot both be `true`.
</Warning>

#### Example with filters

<CodeGroup>
  ```typescript Node theme={null}
  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",
    },
  });
  ```

  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

***

## X402 Support

For agentic workflows, Hyperbrowser supports x402 payment for the Search API, enabling agents to programmatically pay for browser sessions at request time using USDC, with payment handled inline via HTTP 402 responses. See the [X402 Integration](/integrations/x402) page for details.