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 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.

{
  "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

string

required

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

number

default:"5"

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

boolean

default:"false"

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.

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.

object[]

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.

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