# Tavily

Basic normalized retrieval with snippets and reported credits; richer native search and extraction remain explicit.

Canonical: https://searchsdk.dev/docs/providers/tavily
Markdown: https://searchsdk.dev/docs/providers/tavily.md

<a id="overview"></a>

## Normalized search

> **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.

Normalized search selects basic depth, disables generated answers and raw content, requests usage, and uses restrictive native domain inclusion. Native content becomes a snippet; score, request ID, and credits retain their provider meaning.

**tavily-search.ts · server**

```typescript
import { createSearch } from '@belweave/search-sdk';
import { tavily } from '@belweave/search-sdk/tavily';

const apiKey = process.env.TAVILY_API_KEY;
if (!apiKey) throw new Error('TAVILY_API_KEY is required');

const client = createSearch({ provider: tavily({ apiKey }) });
const response = await client.web.search({
  query: 'SQLite write concurrency',
  limit: 5,
});
console.log(response.results, response.attempts);
```

Native search depth and automatic parameter selection can change work and cost. Keep them explicit on the native client. An API account-limit failure is terminal authentication/account authorization, rather than an automatic fallback opportunity.

300 include / 150 exclude.

<a id="native-client"></a>

## Provider-native client

**tavily-native.ts · server**

```typescript
import { createTavilyClient } from '@belweave/search-sdk/native-tavily';

const apiKey = process.env.TAVILY_API_KEY;
if (!apiKey) throw new Error('TAVILY_API_KEY is required');

const client = createTavilyClient({ apiKey, timeoutMs: 10_000 });
const response = await client.search({ body: { query: 'SQLite write concurrency', search_depth: 'basic', max_results: 5 } });
console.log(response.data, response.metadata);
```

Read provider data from `response.data` and sanitized transport details from `response.metadata`. Native TypeScript response types are not runtime schema validation. Preserve the operation's native response and source identities.

<a id="operations"></a>

## Native operation inventory

Methods available on this native client. Paths are relative to each operation's fixed base; a provider may use more than one origin. Eligible operations retry only when you opt into a client retry policy.

| Method | HTTP / relative path | Response / retry eligibility |
| --- | --- | --- |
| `getPaymentPricing` | `GET /.well-known/pricing` | raw · eligible |
| `paidSearch` | `POST /search` | json · no automatic retry |
| `crawl` | `POST /crawl` | json · no automatic retry |
| `deactivateKeys` | `POST /deactivate-keys` | json · no automatic retry |
| `extract` | `POST /extract` | json · no automatic retry |
| `feedback` | `POST /feedback` | json · no automatic retry |
| `generateKeys` | `POST /generate-keys` | json · no automatic retry |
| `keyInfo` | `GET /key-info` | json · eligible |
| `logs` | `POST /logs` | json · no automatic retry |
| `map` | `POST /map` | json · no automatic retry |
| `orgUsage` | `POST /org-usage` | json · no automatic retry |
| `getResearch` | `GET /research/{request_id}` | json · eligible |
| `research` | `POST /research` | json · no automatic retry |
| `researchStream` | `POST /research` | SSE stream · no automatic retry |
| `search` | `POST /search` | json · no automatic retry |
| `getUsage` | `GET /usage` | json · eligible |

<a id="lifecycle"></a>

## Limits and operation lifecycle

- Pass `signal` and per-call `timeoutMs` on native request input when needed.
- Persist a returned job identifier before explicitly reading or polling the same job. Native clients do not automatically poll.
- SSE data is incremental provider event text. Parse and validate terminal or error events according to the provider contract; there is no reconnect or replay.
- Native operations may create, delete, ingest, or incur charges. A successful HTTP response is not proof that a remote job completed.

<a id="sources"></a>

## Official sources

Use the official reference for current schemas, account access, and operation-specific requirements.

- [Search reference](https://docs.tavily.com/documentation/api-reference/endpoint/search)
- [API documentation index](https://docs.tavily.com/llms.txt)

- [Native request and response reference](https://searchsdk.dev/docs/api/native-transport)
- [All providers](https://searchsdk.dev/docs/providers)