Search

POST /v1/web/search runs a query against the web and returns ranked results. By default every result comes back with its page already fetched and cleaned, so a single call turns a question into a set of LLM-ready documents — 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

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"
  }'

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);
}

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, the usual title/url/snippet, and a data object holding the scraped page. When scraping is off or a page can’t be fetched, data is null.

{
  "data": {
    "query": "best open source vector databases",
    "engine": "web",
    "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

string

required

What to search the web for. Up to 500 characters.

number

default:"engine default"

How many ranked results to return, from 1 to 15.

boolean

default:"true"

When true, each result comes back with its page fetched and returned as clean data. Set false to get just the ranked title, url, and snippet — useful when you only need to discover URLs.

object

How to scrape each result, using the same options as 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.

string

Restrict results to a recency window relative to now: day, week, month, or year.

string

ISO 3166 alpha-2 country code (for example us, de) to bias results toward a region.

string[]

Only return results from these domains. Up to 15.

string[]

Drop results from these domains. Up to 15.

Response fields

string

The query you searched.

string

The search source the results came from.

object[]

The ranked results. Each item has title, url, snippet, rank, and data — the scraped page, or null when scraping is off or the page could not be fetched.

Billing

You’re charged 1 credit for the search, plus 1 credit for each result that is actually scraped. A search with scrapeResults set to false costs just the 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.

Scrape

The per-result scrape engine behind search, on a single URL.

Extract

Turn found pages into schema-shaped JSON, or let extract run its own web search.

Formats

Everything scrapeOptions can return per result.

API Reference

Full POST /v1/web/search schema and a live playground.

Get started

Core concepts

Web Scraping

Web Extraction

When to use it

Example request

Example response

Key options

Response fields

Billing

Scrape

Extract

Formats

API Reference

​When to use it

​Example request

​Example response

​Key options

​Response fields

​Billing

​Related

Scrape

Extract

Formats

API Reference

When to use it

Example request

Example response

Key options

Response fields

Billing

Related