> ## 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, research papers and videos for a query in one request, and read the text of each result page when you need it.

Search returns ranked results for a query, one list per source.

```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",
    "limit": 3
  }'
```

```typescript TypeScript theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy();

const { data } = await stophy.search({ query: "bun runtime", limit: 3 });
for (const result of data?.web ?? []) {
  console.log(result.position, result.url);
}
```

```python Python theme={null}
from stophy import Stophy

stophy = Stophy()

data = stophy.search(query="bun runtime", limit=3)["data"]
for result in data["web"]:
    print(result["position"], result["url"])
```

You get 10 web results. Set `limit` from 1 to 100 results per source, and add `news` or `images` to `sources`. Calls without a key have lower limits and cannot read result pages, see [Without a key](https://docs.stophy.dev/production/rate-limits.md#without-a-key).

```json theme={null}
{
  "success": true,
  "data": {
    "web": [
      { "url": "https://bun.com/", "title": "Bun …", "description": "Bundle, install, and run JavaScript & TypeScript …", "position": 1 },
      { "url": "https://en.wikipedia.org/wiki/Bun_(software)", "title": "Bun (software) - Wikipedia", "position": 2, "date": "2026-11-06" }
    ]
  }
}
```

Each source's list is in `data`, such as `data.web`, ranked by `position`. A web row has `url`, `title` and `description`, plus `date` when known and `category` (`github`, `research` or `pdf`) when the page is one of those. A news row has `snippet` instead of `description`.

## Fields

| Field | Default | What it does |
| - | - | - |
| `query` | required | 1 to 500 characters. Web results take `"exact phrase"`, `-word`, `site:`, `-site:`, `filetype:`, `inurl:`, `allinurl:`, `intitle:` and `allintitle:`. Images take `imagesize:WIDTHxHEIGHT` and `larger:WIDTHxHEIGHT`. |
| `sources`, `categories` | `["web"]` | `web`, `news` and `images`, or `pdf`, `research` and `videos`. See [Sources](https://docs.stophy.dev/search/options.md#sources). |
| `limit` | 10, or 5 with `scrapeOptions.formats` | Results per source, 1 to 100. News returns at most 50. |
| `includeDomains`, `excludeDomains`, `tbs`, `location`, `country`, `lang`, `safe` | none | Narrow by site, time, place or language. See [Filters](https://docs.stophy.dev/search/options.md#filters). |
| `scrapeOptions`, `scrapeLimit`, `highlights` | none | Read each result page, or only its matching passages. See [Page content](https://docs.stophy.dev/search/options.md#page-content). |
| `maxAge` | 1 hour, 15 minutes for news | Accept a stored answer this many milliseconds old, at most 30 days. `0` searches live. |
| `ignoreInvalidURLs` | `false` | Leave out results whose address is not a readable page. |

## Errors

A source that fails, or has not answered within `timeout`, is left out and named in `warning`, and the call still succeeds. Raise `timeout` as in [Timeouts](https://docs.stophy.dev/production/timeouts.md). If every source fails, the call fails and costs nothing. Every code is in [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Next

* [Search options](https://docs.stophy.dev/search/options.md): sources, filters and page text.
* [Papers](https://docs.stophy.dev/search/papers.md) and [Developer search](https://docs.stophy.dev/search/developer.md): search one kind of content.
* [Scrape](https://docs.stophy.dev/scrape/overview): read one result in full.


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