---
title: "Search the web"
method: POST
path: "/v1/data/web/search"
tags: ["Web: Search"]
---

# Search the web

`POST /v1/data/web/search`

## Request

- Base URL: `https://api.superagnt.com`
- URL: `https://api.superagnt.com/v1/data/web/search`
- Auth: API key in header `Authorization`

Runs a web search and returns result URLs + snippets — cheap; use this first and read the snippets. Add `scrapeOptions` ONLY when you actually need the full text of the pages, because it then downloads and bills EVERY result — keep `limit` small when you do (a few results, not dozens). To read specific pages, prefer searching first and then scraping just the one or two URLs you chose. Supports web, news, and image sources.

## Request body

- object
  - `query` string, required: The search query.
  - `limit` integer: Number of results per source. Default 10.
  - `sources` union[]: Which result sources to query. Defaults to ['web']. Each entry is a preset string or an object with a `type`.
    - union
      - 'web' | 'news' | 'images'
      - object
        - `type` 'web' | 'news' | 'images', required
  - `categories` string[]: Restrict results to these categories.
  - `tbs` string: Time-based search filter (e.g. 'qdr:d' for past day).
  - `location` string: Geo-target for the search (e.g. 'San Francisco, California, United States').
  - `country` string: ISO country code. Default 'US'.
  - `includeDomains` string[]: Only return results from these hostnames (mutually exclusive with excludeDomains).
  - `excludeDomains` string[]: Exclude results from these hostnames (mutually exclusive with includeDomains).
  - `timeout` integer: Request timeout in milliseconds. Default 60000.
  - `scrapeOptions` object: When provided, each result is also scraped and its content returned. Accepts the same content options as /scrape (e.g. `formats`, `onlyMainContent`). Increases cost because every result is fetched.
    - `formats` unknown[]: Output formats for each scraped result (e.g. ['markdown']).
      - unknown
    - `onlyMainContent` boolean

## Response `200`

Search results, optionally including scraped page content.

- object

## Other responses

- `400`: Bad request — missing `query` or invalid parameter.
- `401`: Unauthorized.
- `402`: Insufficient balance.
- `429`: Too many requests.
- `5XX`: Upstream error.

---

[API](https://skmtc.dev/superagnt/apis/superagnt-api.md) · [All operations](https://skmtc.dev/superagnt/apis/superagnt-api/llms.txt) · [OpenAPI document](https://skmtc.dev/superagnt/apis/superagnt-api/revisions/b2d8de30ccf0?raw)