# Search API

`POST /v1/answers/search` is the search tool behind [Answers](/answers). It
returns ranked sources for a query, each with the text on the page that matches
it, and writes no answer: your agent reads the sources and reasons over them.
Use [`ask`](/answers) instead when you want one checked answer.

On DeepSearchQA, Hyperresearch Search scores 89% and Exa scores 72%. Exa ranks top on Artificial Analysis's Search Index. Hyperresearch Search was tested in standard mode as it runs in production, where every call queries Parallel's and Exa's search APIs and reranks their results with our own sources. So our results include Exa's; the Exa row is Exa's search API on its own.

Every search queries the open web and about 45 structured sources (company
filings, statistics agencies, scholarly indexes, books, government records),
merges and dedupes what comes back, and ranks it against the query.

## Where the results come from

The web results come from outside search providers we pay for. Every search
queries Parallel's and Exa's web search APIs; `max` also queries Valyu's. We
then read the top pages ourselves. When a page will not load directly we use an
archived copy or Valyu's reader, and a PDF may be read through Valyu or
Firecrawl. A result we did not read ourselves keeps the excerpt its search
provider returned, marked `verified: false`. In the response, `source` says
`web` for a result from any of these web indexes; it does not say which one.
Results contain third-party material, and the
[Terms](/legal/terms) say how you may use them.

## Request

```bash
curl https://api.hyperresearch.ai/v1/answers/search \
  -H "Authorization: Bearer $HYPERRESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "EU member states with a population over 10 million that use the euro", "max_results": 10}'
```

| Field | Type | Default | |
|---|---|---|---|
| `query` | string, 1-1,000 characters | required | A search query. `site:example.com` restricts the web results to that domain. |
| `max_results` | integer, 1-25 | 10 | Results returned at most. |
| `mode` | `standard` or `max` | `standard` | See below. |

The key needs the `answers:ask` scope. Send an `Idempotency-Key` header to
retry safely: the same key and body replay the first call with one charge.

## Modes

| Mode | What it does | Typical time | Price |
|---|---|---|---|
| `standard` | The web indexes and the structured sources, the top pages read live, ranked by a model | 10-20 s | 5¢ |
| `max` | Every web index on every call, the full structured-source walk, tables read out of PDFs, a deeper rerank | 20-45 s | 15¢ |

A search that fails on our side is free. One that completes with no results is
free unless it was expensive to run (then 1.5x our cost, at most the mode price).

## Response

```json
{
  "id": "ans_01J9ZQ7V6H0000000000000000",
  "query": "EU member states with a population over 10 million that use the euro",
  "status": "ok",
  "mode": "standard",
  "results": [
    {
      "rank": 1,
      "url": "https://european-union.europa.eu/institutions-law-budget/euro/countries-using-euro_en",
      "title": "Countries using the euro",
      "published": "2025-01-01T00:00:00.000Z",
      "source": "web",
      "kind": "web",
      "snippet": "20 of the 27 EU member states use the euro …",
      "passages": [{ "text": "20 of the 27 EU member states use the euro: Austria, Belgium, Croatia, …", "verified": true }]
    }
  ],
  "meta": { "ms": 11840, "mode": "standard", "reranked": true, "fetched": 6 },
  "price_cents": 5,
  "balance_cents": 495
}
```

Each result:

- `rank`: 1 is the best match.
- `url`, `title`.
- `published`: the page date (ISO 8601) when a source dated it.
- `source`: `web` for the open web (any of the web search providers above), or
  the structured source a record came from (for example `edgar`, `openalex`,
  `worldbank`).
- `kind`: `web` a page, `record` a structured-source record, `data` rows of a
  dataset.
- `snippet`: a short lead. The passages carry the full text.
- `passages`: the text that matches the query, plain text with no Markdown
  links. `verified: true` means the passage was cut word for word from the live
  page; `false` means it is the excerpt a search provider (Parallel, Exa or
  Valyu) returned.

`meta.errors` lists one `{ "kind": "source_unavailable" }` per source that
failed during the call; the rest of the results still come back.

## Limits and errors

`ask` and `search` together are limited to 60 calls a minute per API key and
120 a minute per workspace, and an account runs at most 10 Answers calls at
once. Past either limit the API answers `429` with `Retry-After`. A call your
balance cannot cover is a `402` with a top-up link; see [Billing](/docs/billing)
and [Errors](/docs/errors).

The full schema is in the [API reference](/docs/api/operations/tags/answers).