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

# Search

> Find web pages, news, images, papers and videos from a query in one request. Add the page text of each result. $1 per 1,000 searches of up to 10 results.

Search finds pages from a query and returns them ranked, grouped by source. Pick the sources in `sources`; with no `sources` you get web results.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request searches the web and the news for three results each.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/search \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "bun runtime",
    "sources": ["web", "news"],
    "limit": 3
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "bun runtime",
    sources: ["web", "news"],
    limit: 3,
  }),
});
const { data } = await response.json();
for (const result of data.web) {
  console.log(result.position, result.title, result.url);
}
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/search",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "query": "bun runtime",
        "sources": ["web", "news"],
        "limit": 3,
    },
)
data = response.json()["data"]
for result in data["web"]:
    print(result["position"], result["title"], result["url"])
```

You can try Search without an API key, up to 10 calls a minute and 50 calls a day per IP address. Reading the page text of each result needs an API key. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md).

## Read the response

`data` holds one list for each source you asked for. Every row has a `position`. This real response is cut to the first rows of each list. Each news row also has an `imageUrl`.

```json theme={null}
{
  "success": true,
  "data": {
    "news": [
      {
        "title": "Bun v1.4.4 | Bun Blog",
        "url": "https://bun.com/blog/bun-v1.4.4",
        "snippet": "Build errors are shown once, not twice, when a file is bundled for both the server and the browser, like a stylesheet imported by a page.",
        "date": "2026-10-18T07:38:17.000Z",
        "position": 2
      }
    ],
    "web": [
      {
        "url": "https://github.com/oven-sh/bun",
        "title": "GitHub - oven-sh/bun: Incredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one · GitHub",
        "description": "At its core is the Bun runtime, a fast JavaScript runtime designed as a drop-in replacement for Node.js.",
        "position": 1,
        "category": "github",
        "date": "2026-11-13T00:00:00.000Z"
      },
      {
        "url": "https://bun.com/docs/runtime",
        "title": "Bun Runtime | Bun Docs",
        "description": "Execute JavaScript/TypeScript files, package.json scripts, and executable packages with Bun's fast runtime.",
        "position": 2
      }
    ]
  },
  "id": "4d7b5096-0898-4a64-8438-5048c681b2b1",
  "costUsd": 0.002,
  "requestId": "4d7b5096-0898-4a64-8438-5048c681b2b1"
}
```

A web row has a `url`, a `title` and a `description`. `date` appears when the date of the page is known, and `category` is `github`, `research` or `pdf` when the page is one of those. A news row has a `snippet` instead of a `description`. `costUsd` is what the call cost.

If a source answers with fewer results than you asked for, or fails while the others work, the call still succeeds and `warning` says which. If every source fails, the call fails and costs nothing.

## Options

| Option | What you get | Guide |
| - | - | - |
| `sources`, `categories` | Web, news and image results, and lists of papers, PDFs and YouTube videos | [Sources](https://docs.stophy.dev/search/sources.md) |
| `includeDomains`, `excludeDomains`, `tbs`, `location`, `country`, `lang`, `safe` | Results narrowed by site, time, place, language or safety | [Filters](https://docs.stophy.dev/search/filters.md) |
| `scrapeOptions`, `highlights` | The page text or the best passages of each result | [Page content](https://docs.stophy.dev/search/page-content.md) |
| `POST /v1/search/developer` | Code docs, READMEs, issues, pull requests and releases | [Developer search](https://docs.stophy.dev/search/developer.md) |
| `POST /v1/search/research/papers` | Research papers by title and abstract, one paper by id, and similar papers | [Papers](https://docs.stophy.dev/search/papers.md) |

These fields belong to this page.

| Field | Type | Default | Effect |
| - | - | - | - |
| `query` | `string` | none | What to search for, 1 to 500 characters. Required. Web results take the operators `"exact phrase"`, `-word`, `site:`, `-site:`, `filetype:`, `inurl:`, `allinurl:`, `intitle:` and `allintitle:`. Image results take `imagesize:WIDTHxHEIGHT` for that size and larger, and `larger:WIDTHxHEIGHT` for at least that size. |
| `limit` | `number` | 10, or 5 with `scrapeOptions.formats` | The most results from each source, 1 to 100. News returns at most 50. |
| `maxAge` | `number` | 1 hour, or 15 minutes with `news` | Accept a stored answer up to this many milliseconds old, at most 30 days. `0` always searches live. An answer that was stored has `cachedAt`. |
| `timeout` | `number` | 3,000 ms, or 60,000 ms with `scrapeOptions.formats` | Milliseconds to wait for the sources, from 1,000 to 120,000. A source that has not answered is left out with a warning. |
| `ignoreInvalidURLs` | `boolean` | `false` | Leave out results whose address cannot be read as a page. |

The full field list is in the [API reference](https://docs.stophy.dev/api-reference/endpoint/search.md).

## Price

$1 per 1,000 searches of up to 10 results: $0.001 for each 10 results from each source, and for each list of papers or videos. A search that returns nothing costs nothing. Page text adds $1 per 1,000 results read, and `summary` or `json` with a schema or a prompt add $3 per 1,000 more each. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Choose another API

* [Scrape](https://docs.stophy.dev/scrape/overview) reads one page you already know.
* [Extract](https://docs.stophy.dev/extract/overview) pulls the fields you name from pages, each checked against the page.
* [Agent](https://docs.stophy.dev/agent/overview) searches and reads for you until your fields are filled.
* [Crawl](https://docs.stophy.dev/crawl/overview) reads every page of a site in the background.
* [Map](https://docs.stophy.dev/map/overview) lists the pages of a site without reading them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.