# web.search

The portable request for ranked web results, with capability checks before dispatch.

Canonical: https://searchsdk.dev/docs/api/search
Markdown: https://searchsdk.dev/docs/api/search.md

<a id="request"></a>

## Request fields

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

| Field | Contract |
| --- | --- |
| `query: string` | Required, nonblank; forwarded unchanged. |
| `limit?: number` | Integer 1–20; default 5. Output ceiling. |
| `includeDomains?: readonly string[]` | Nonempty hostname allowlist within every provider's capacity. |
| `excludeDomains?: readonly string[]` | Nonempty hostname blocklist within every provider's capacity. |

<a id="options"></a>

## Call options

**TypeScript**

```typescript
const controller = new AbortController();
// client is a configured createSearch() client.
const response = await client.web.search(
  { query: 'SQLite write concurrency', limit: 5 },
  { signal: controller.signal },
);
```

Only `signal` is accepted in normalized call options. Unknown request or option fields reject with `invalid_request`; a required capability missing from any configured provider rejects with `unsupported_option`. Native options belong on the provider-native surface.

<a id="result-count"></a>

## Result-count behavior

A successful response can contain zero or fewer than the requested number of results. Empty success does not trigger fallback. TinyFish fetches one first page; Context requests at least ten native results and trims to the requested ceiling. The SDK does not silently paginate.

- [Response shape](https://searchsdk.dev/docs/api/response)
- [Domain filter rules](https://searchsdk.dev/docs/guides/domain-filters)