# Search

> Run normalized public web search.

Source page: https://docs.replynodes.com/docs/guides/search

# Search

`GET /v1/web/search` is the canonical `web_search`-tagged web-search operation. It searches the public web in English through the normalized Web Search provider contract (version `v2`). The required query parameter is `q`; optional parameters are `language`, `engines`, `page`, `time_range`, and `limit`. Pass only parameters declared by the contract: unknown, repeated, or removed parameters (`text`, `lang`, `region`, `date`, `site`, `start`, `cursor`) are rejected with `400 invalid_request`. Exact result fields are in the generated [API Reference](https://docs.replynodes.com/reference).

## Set the query

Use `q` for the search query: 1 to 512 bytes, with no control characters. Tokens that start with `!`, `:`, or `<` are reserved and rejected. Ordinary `site:example.com` text is passed to the engine as search syntax; it is not a guaranteed filter and there is no dedicated site parameter. `language` is `en-US` (the default) or `en-GB`. `engines` is an optional comma-separated list of approved engines (`brave`, `bing`); omit it to use the default chain, which tries Brave and falls back to Bing only when Brave fails. `page` is an upstream page number, not an offset: the current engine profile supports pages 1 and 2, and higher pages are rejected with `400 invalid_request`. `time_range` accepts `week`; `day` and `month` are rejected until they are verified. A time range is not available on the Bing fallback. `limit` is the number of records returned from the merged page, 1 through 50; it truncates and never creates a cursor.

The operation is a read-only `GET` request. A successful response uses the standard `{ data, meta }` envelope, and the correlation identifier is returned as `meta.request_id` and in the `X-Request-Id` header. Invalid requests use the normalized error envelope. When a request receives `429`, honor `Retry-After` before retrying.

## Read the response

The v2 search payload (the `data` object of the standard envelope) has exactly three keys. `data` is an array of records (an empty array is a verified empty search): each record has `id`, `platform`, `rank` (one-based within the returned page, not a global rank), `title`, `snippet`, `domain`, `url`, and `engines`, the engines that actually returned it. `pagination` is `{ page, next_page: null, has_more: null }`: continuation is never promised, so request another page explicitly. `meta` has `contract_version`, `generated_at`, `source`, `availability`, `engines_requested`, and `engines_failed`.

`availability` is `complete` or `partial`. A partial response, for example one served by the Bing fallback after Brave failed or one that dropped an invalid result URL, is still a successful billed read; it lists the failed engines in `engines_failed` and is never served from a cache. If no engine can be verified as having run, the request fails with `502 upstream_unavailable` and is not billed.

## Make a request

Store `REPLYNODES_API_KEY` in a secret store, then send it as a bearer credential:

```bash
curl -sS \
  -H "Authorization: Bearer $REPLYNODES_API_KEY" \
  "https://api.replynodes.com/v1/web/search?q=public%20web%20data%20site%3Areplynodes.com&limit=5"
```

See [Quickstart](https://docs.replynodes.com/docs/quickstart) for the shared authentication pattern, [Web context](https://docs.replynodes.com/docs/guides/web) for public-page extraction, and the [API Reference](https://docs.replynodes.com/reference) for the current operation schema.

Build a search request from the smallest set of constraints that answers the question. Keep the complete parameter set with the result, because changing language or engine selection can legitimately produce a different ordering and different documents. Request page 2 explicitly when you need more, and stop when results stop being useful. Do not assume that a result is current, complete, or ranked identically on a later request.

This route returns normalized public search data and does not provide a private search session or a write operation. The generated [API Reference](https://docs.replynodes.com/reference) defines the envelope and result fields; the deployed runtime capability document is authoritative if availability changes. Preserve `request_id` values for support and observability. Handle `429` with the server's `Retry-After` guidance and use finite retries for transient failures. Avoid replaying the same broad query indefinitely, especially when an agent is paging on behalf of another workflow.