# Search

`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

```bash tab="cURL"
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}'
```

```javascript tab="JavaScript"
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);
```

```python tab="Python"
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:

```json title="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](/docs/billing).