Search

POST /v1/search runs a web search and returns the results as JSON.

POST https://api.happyfetch.net/v1/search

Request#

Field	Type	Default	Meaning
`query`	string, 1–500 characters	required	What to search for, as you'd type it into a search engine.
`max_results`	integer, 1–50	`10`	The most results to return.
`region`	string like `nl-nl`, `us-en`	`""`	The search region. Leave it empty for no region.
`max_age`	integer, seconds	24 hours	The oldest cached answer you accept. `0` forces a fresh search.

Example#

curl https://api.happyfetch.net/v1/search --max-time 120 \
  -H "Authorization: Bearer $HAPPYFETCH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"stripe","max_results":5}'

const res = await fetch("https://api.happyfetch.net/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HAPPYFETCH_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(), // send the same key when you retry this call
  },
  body: JSON.stringify({
    "query": "stripe",
    "max_results": 5
  }),
  signal: AbortSignal.timeout(120_000),
});
const { data, meta, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(meta.request_id, meta.cache.status, data);

import os, uuid, requests

res = requests.post(
    "https://api.happyfetch.net/v1/search",
    headers={
        "Authorization": f"Bearer {os.environ['HAPPYFETCH_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # send the same key when you retry this call
    },
    json={
      "query": "stripe",
      "max_results": 5
    },
    timeout=120,
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["meta"]["request_id"], body["meta"]["cache"]["status"])

Response#

data.results is the list of hits, in ranking order:

Field	Meaning
`title`	The result title.
`href`	The result URL.
`body`	The snippet.

The complete response to the example above, exactly as the API returns it:

200 OK

{
  "data": {
    "results": [
      {
        "title": "Stripe Login | Sign in to the Stripe Dashboard",
        "href": "https://dashboard.stripe.com/",
        "body": "Sign in to the Stripe Dashboard to manage business payments and operations in your account. Manage payments and refunds, respond to disputes and more."
      },
      {
        "title": "Stripe | Financial Infrastructure to Grow Your Revenue",
        "href": "https://stripe.com/",
        "body": "Stripe is a financial services platform that helps all types of businesses accept payments, build flexible billing models, and manage money movement."
      },
      {
        "title": "Sign up and create a Stripe account | Stripe",
        "href": "https://dashboard.stripe.com/register",
        "body": "Sign up to quickly create a new Stripe account today and get started accepting payments in minutes."
      },
      {
        "title": "Stripe Payments | Global Payment Processing Platform",
        "href": "https://stripe.com/payments",
        "body": "Capture more revenue with a unified payments solution that eliminates the need for one-off merchant account, payment gateway, and processor integrations."
      },
      {
        "title": "Stripe, Inc. - Wikipedia",
        "href": "https://en.wikipedia.org/wiki/Stripe,_Inc.",
        "body": "Stripe, Inc. is an Irish-American fintech company that offers payment-processing software and APIs for e-commerce and mobile apps. Founded in 2010 by Patrick and John Collison, Stripe has a valuation of $91 billion and partners with major enterprises such as Ford, Spotify, and OpenAI."
      }
    ]
  },
  "meta": {
    "request_id": "3b2f6a1e-9c4d-4e7a-b815-2f60d4c9a7e3",
    "endpoint": "search",
    "credits_charged": 1,
    "credits_remaining": 199,
    "cache": {
      "status": "miss",
      "age_seconds": 0,
      "fetched_at": "2026-09-23T06:50:34.000Z",
      "max_age_seconds": 86400
    },
    "content_hash": "sha256:6ffee583fd2ff669e82c001c7d23269b4a51dead178a4e70a8f8c1e35deddd81"
  }
}

An empty results list is a completed search: the search ran and found nothing, so it's billed.

Price#

A web search costs 1 credit, fetched now or from our cache, even when it finds nothing. Searches we can't complete are refunded automatically. See Credits, billing and refunds.