> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydrafetch.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> Search the web and get ranked results, each scraped to clean data.
`POST /v1/web/search` runs a query against the web and returns ranked results. Turn on `scrapeResults` and every result also comes back with its page already fetched and cleaned, so a single call turns a question into a set of LLM-ready documents with no second round of scraping.
## When to use it
* You know what you're looking for but not the exact URLs — let a query find the pages.
* You want the top few sources on a topic returned as clean Markdown, ready to feed a model.
* You need to bias results to a region, a recency window, or a specific set of domains.
Search is synchronous: send the query, get results back in one response.
## Example request
```bash cURL theme={null}
curl -X POST https://api.hydrafetch.com/v1/web/search \
-H "X-API-Key: hf_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"query": "best open source vector databases",
"limit": 3,
"timeRange": "month"
}'
```
```javascript Node theme={null}
const res = await fetch("https://api.hydrafetch.com/v1/web/search", {
method: "POST",
headers: {
"X-API-Key": "hf_your_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
query: "best open source vector databases",
limit: 3,
timeRange: "month",
}),
});
const { data } = await res.json();
for (const r of data.results) {
console.log(r.rank, r.title, r.url);
console.log(r.data?.markdown);
}
```
```python Python theme={null}
import requests
res = requests.post(
"https://api.hydrafetch.com/v1/web/search",
headers={"X-API-Key": "hf_your_key_here"},
json={
"query": "best open source vector databases",
"limit": 3,
"timeRange": "month",
},
)
for r in res.json()["data"]["results"]:
print(r["rank"], r["title"], r["url"])
print((r["data"] or {}).get("markdown"))
```
## Example response
Each result carries its rank and the usual title/url/snippet. Turn on `scrapeResults` and each one also carries a `data` object holding the scraped page; otherwise `data` is `null`.
```json theme={null}
{
"data": {
"query": "best open source vector databases",
"status": "ok",
"results": [
{
"title": "Best open source vector databases",
"url": "https://example.com/vector-databases",
"snippet": "A rundown of the leading open source vector databases and how they compare.",
"rank": 1,
"data": {
"url": "https://example.com/vector-databases",
"finalUrl": "https://example.com/vector-databases",
"status": 200,
"metadata": { "title": "Best open source vector databases", "pageType": "article" },
"markdown": "# Best open source vector databases\n\n..."
}
}
]
}
}
```
## Key options
What to search the web for. Up to 500 characters.
How many ranked results to return, from 1 to 15.
When `true`, each result also comes back with its page fetched and returned as clean data, at **1 extra credit per page scraped**. Leave it off to get just the ranked title, url, and snippet for the flat search credit.
How to scrape each result, using the same options as [Scrape](/endpoints/scrape) — pick `formats`, force JavaScript rendering, set a per-page `timeout`, choose a `location`, and more. Applied to every result. Ignored when `scrapeResults` is `false`.
Restrict results to a recency window relative to now: `day`, `week`, `month`, or `year`.
ISO 3166 alpha-2 country code (for example `us`, `de`) to bias results toward a region.
Only return results from these domains. Up to 15.
Drop results from these domains. Up to 15.
## Response fields
The query you searched.
The ranked results. Each item has `title`, `url`, `snippet`, `rank`, and `data` — the scraped page when `scrapeResults` is on, otherwise `null`.
## Billing
A search costs **1 credit**. If you turn on `scrapeResults`, each result that is actually scraped costs **1 more**, the same as scraping that page directly. Scraping is off by default, so a plain search is always 1 credit. As always, you're charged only on success, and the response reports what it consumed.
Richer `scrapeOptions` formats on each result can raise the per-result cost, the same way they do for a direct scrape. See [Credits](/concepts/credits).
## Related
The per-result scrape engine behind search, on a single URL.
Turn found pages into schema-shaped JSON, or let extract run its own web search.
Everything `scrapeOptions` can return per result.
Full `POST /v1/web/search` schema and a live playground.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.