> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices for Search

> Optimize individual queries, and run search reliably at scale with batch workflows.

## Query Optimization

### Keep your query under 1500 characters

Keep queries concise—under **1500 characters**. Think of it as a query for an agent performing web search, not long-form prompts.

### Break complex queries into sub-queries

For complex or multi-topic queries, send separate focused requests:

```json theme={null}
// Instead of one massive query, break it down:
{ "query": "Competitors of company ABC." }
{ "query": "Financial performance of company ABC." }
{ "query": "Recent developments of company ABC." }
```

## Search Depth

The `search_depth` parameter controls the tradeoff between latency and relevance:

**Latency vs relevance chart**

![Latency vs Relevance by Search Depth](https://mintcdn.com/tavilyai/-85Rr9EfVqo8fXvO/images/search-depth.png?fit=max\&auto=format\&n=-85Rr9EfVqo8fXvO\&q=85\&s=c57f2074dda171a1e3e9f96afbec8f10)

*This chart is a heuristic and is not to scale.*

| Depth | Latency | Relevance | Content Type |
| - | - | - | - |
| `ultra-fast` | Lowest | Lower | Content |
| `fast` | Low | Good | Chunks |
| `basic` | Medium | High | Chunks |
| `advanced` | Higher | Highest | Chunks |

### Content types

| Type | Description |
| - | - |
| **Content** | NLP-based summary of the page, providing general context |
| **Chunks** | Short snippets reranked by relevance to your search query |

Use **chunks** when you need highly targeted information aligned with your query. Use **content** when a general page summary is sufficient.

### `basic` vs `advanced`

`advanced` searches more broadly and reaches more sources per query, delivering the highest
relevance at higher latency. Reach for it when coverage matters most: niche topics, very
recently published pages, or questions with several distinct facets.

Longer, more detailed queries also do better with `advanced` — the extra context gives it
more to match against, whereas `basic` is tuned for short, focused lookups.

`basic` covers less ground for a lower latency budget, making it the right default for
general-purpose lookups where a fast, query-aligned answer is enough.

Both depths return chunks, and `chunks_per_source` controls how many come back per source
at either depth.

> [!NOTE]
>
> `basic` previously returned a single page summary per source. It now returns reranked
> chunks. See the [changelog](https://docs.tavily.com/changelog.md) entry for details.

### Fast + Ultra-Fast

| Depth | When to use |
| - | - |
| `ultra-fast` | When latency is absolutely crucial. Delivers near-instant results, prioritizing speed over relevance. Ideal for real-time applications where response time is critical. |
| `fast` | When latency is more important than relevance, but you want results in reranked chunks format. Good for applications that need quick, targeted snippets. |
| `basic` | A solid balance between relevance and latency. Returns reranked chunks. Best for general-purpose searches where you need quality results without the overhead of advanced processing. |
| `advanced` | When you need the highest relevance and are willing to trade off latency. Best for queries seeking specific, detailed information. |

### Using `search_depth=advanced`

Best for queries seeking specific information:

```json theme={null}
{
  "query": "How many countries use Monday.com?",
  "search_depth": "advanced",
  "chunks_per_source": 3,
  "include_raw_content": true
}
```

## Filtering Results

### By date

| Parameter | Description |
| - | - |
| `time_range` | Filter by relative time: `day`, `week`, `month`, `year` |
| `start_date` / `end_date` | Filter by specific date range (format: `YYYY-MM-DD`) |
| `include_published_date` | Return a `published_date` field on each result. Beta. Automatically enabled when `topic` is `news`. |
| `filter_by_published_date` | Strictly remove results outside the `time_range`/`start_date`/`end_date` window, **and** remove results with no detectable published date. |

```json theme={null}
{ "query": "latest ML trends", "time_range": "month" }
{ "query": "AI news", "start_date": "2025-01-01", "end_date": "2025-02-01" }
```

> [!WARNING]
>
> Date filters match a page's publish date, not its last update. Continuously updated pages (weather forecasts, prices, exchange rates) often have old publish dates, so date filters drop them and less relevant pages fill in. Leave date filters unset for these queries, and set [`max_age_hours`](#by-content-freshness) if you need a recent copy of each page.

### By content freshness

Date filters choose pages by when they were published. `max_age_hours` sets how recently Tavily must have fetched each page, so you get the current version of pages whose content changes often.

| Value | Behavior |
| - | - |
| unset | Default. Tavily serves cached copies and fetches pages live as needed |
| `1`-`720` | Only return a cached copy fetched within that many hours |
| `0` | Always fetch the page live |
| `-1` | Never fetch live |

Set it when the answer depends on content that changes often:

* Weather forecasts
* Prices, stock levels, and availability on product pages
* Live scores, standings, and match pages
* Status pages and incident trackers
* News articles that are updated as a story develops
* Stock quotes and exchange rates
* Job postings and event listings that open and close

```json theme={null}
// Weather forecast
{ "query": "London 7 day weather forecast", "max_age_hours": 24 }

// Product price that changes during the day
{ "query": "iPhone 17 Pro price Best Buy", "max_age_hours": 6 }

// Live match score
{ "query": "Real Madrid vs Barcelona score", "max_age_hours": 0 }

// Current status of a service outage
{ "query": "GitHub Actions status incident", "max_age_hours": 1 }
```

Leave it unset for content that rarely changes, such as documentation, encyclopedia entries, and research papers. Lower values do not cost more credits, but fetching live adds latency.

> [!NOTE]
>
> You may get fewer results than `max_results`. When a page's cached copy is older than `max_age_hours` and Tavily can't fetch the page live, the page is left out of the results.

> [!NOTE]
>
> On non-paying plans, live fetching is best-effort. While Tavily is under heavy load, requests that set `max_age_hours` may be refused with `434 Flex tier capacity exceeded`. See [Flex Tier Capacity](https://docs.tavily.com/documentation/rate-limits.md#flex-tier-capacity).

### By topic

Use `topic` to filter by content type. Set to `news` for news sources (includes `published_date` metadata):

```json theme={null}
{ "query": "What happened today in NY?", "topic": "news" }
```

### By domain

| Parameter | Description |
| - | - |
| `include_domains` | Limit to specific domains |
| `include_domains_mode` | Defaults to `restrict`: `include_domains` is a hard filter. Set to `prefer` to also search the rest of the web, so results outside `include_domains` can still surface. |
| `exclude_domains` | Filter out specific domains |
| `country` | Boost results from a specific country |

```json theme={null}
// Restrict to LinkedIn profiles
{ "query": "CEO background at Google", "include_domains": ["linkedin.com/in"] }

// Prefer trusted sources without excluding everything else
{ "query": "quarterly earnings outlook", "include_domains": ["bloomberg.com", "reuters.com"], "include_domains_mode": "prefer" }

// Exclude irrelevant domains
{ "query": "US economy trends", "exclude_domains": ["espn.com", "vogue.com"] }

// Boost results from a country
{ "query": "tech startup funding", "country": "united states" }

// Wildcard: limit to .com, exclude specific site
{ "query": "AI news", "include_domains": ["*.com"], "exclude_domains": ["example.com"] }
```

> [!NOTE]
>
> Keep domain lists short and relevant for best results.

> [!NOTE]
>
> `include_domains_mode: "prefer"` is useful when you want to prioritize trusted sources without risking empty results if none of them cover the query.

### By language

| Parameter | Description |
| - | - |
| `language` | Boost results in a specific language. Accepts an ISO 639-1 code (`en`, `fr`, `zh-cn`) or an English language name (`english`, `french`). |
| `filter_by_language` | Strictly drop results that don't match `language`, instead of only boosting them. Requires `language` to be set. |

```json theme={null}
// Boost French results, but still allow other languages through
{ "query": "actualités technologiques", "language": "french" }

// Strictly return only French-language results
{ "query": "actualités technologiques", "language": "fr", "filter_by_language": true }
```

> [!NOTE]
>
> `filter_by_language` can return fewer results — or none — when few sources match the requested language. Use it only when a mismatched-language result would be worse than no result; otherwise rely on `language` alone for a soft boost.

> [!TIP]
>
> For best results, write your `query` in the same language you pass to `language`. Search ranking is optimized when the query and target language match.

## Response Content

### `max_results`

Limits results returned (default: `5`). Setting too high may return lower-quality results.

### `include_raw_content`

Returns full extracted page content. For comprehensive extraction, consider a two-step process:

1. Search to retrieve relevant URLs
2. Use [Extract API](https://docs.tavily.com/documentation/best-practices/best-practices-extract.md#2-two-step-process-search-then-extract) to get content

### `auto_parameters`

Tavily automatically configures parameters based on query intent. Your explicit values override automatic ones.

```json theme={null}
{
  "query": "impact of AI in education policy",
  "auto_parameters": true,
  "search_depth": "basic" // Override to control cost
}
```

> [!NOTE]
>
> `auto_parameters` may set `search_depth` to `advanced` (2 credits). Set it
> manually to control cost.

## Exact Match

Use `exact_match` only when searching for a specific name or phrase that must appear verbatim in the source content. Wrap the phrase in quotes within your query:

```json theme={null}
{
  "query": "\"John Smith\" CEO Acme Corp",
  "exact_match": true
}
```

Because this narrows retrieval, it may return fewer results or empty result fields when no exact matches are found. Best suited for:

* **Due diligence** — finding information on a specific person or entity
* **Data enrichment** — retrieving details about a known company or individual
* **Legal/compliance** — locating exact names or phrases in public records

## Async & Batch Search

Use async calls for concurrent requests:

```python Python theme={null}
import asyncio
from tavily import AsyncTavilyClient

client = AsyncTavilyClient("tvly-YOUR_API_KEY")
queries = ["Tavily API pricing", "Tavily rate limits", "Tavily search features"]

async def main():
    responses = await asyncio.gather(
        *(client.search(q) for q in queries),
        return_exceptions=True,
    )
    for r in responses:
        print(f"Failed: {r}" if isinstance(r, Exception) else r)

asyncio.run(main())
```

```javascript JavaScript theme={null}
const { tavily } = require("@tavily/core");
const client = tavily({ apiKey: "tvly-YOUR_API_KEY" });
const queries = ["Tavily API pricing", "Tavily rate limits", "Tavily search features"];

const responses = await Promise.allSettled(queries.map((q) => client.search(q)));
for (const r of responses) {
  console.log(r.status === "rejected" ? `Failed: ${r.reason}` : r.value);
}
```

### Parallelize with bounded concurrency

For larger batches, cap in-flight requests to stay under your [rate limit](https://docs.tavily.com/documentation/rate-limits.md), and tag each result so one failure (e.g. a `429`) doesn't sink the whole batch.

```python Python theme={null}
import asyncio

sem = asyncio.Semaphore(20)  # in-flight cap; keep under your RPM

async def search_one(q, **kw):
    async with sem:
        for attempt in range(5):
            try:
                return {"query": q, "ok": True, "data": await client.search(q, **kw)}
            except Exception as e:
                if attempt == 4:
                    return {"query": q, "ok": False, "error": str(e)}
                await asyncio.sleep(2 ** attempt)  # exponential backoff

async def batch_search(queries, **kw):
    return await asyncio.gather(*(search_one(q, **kw) for q in queries))

results = asyncio.run(batch_search(queries, search_depth="advanced"))
```

```javascript JavaScript theme={null}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// reuses `client` and `queries` from above
async function searchOne(query, options = {}) {
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      return { query, ok: true, data: await client.search(query, options) };
    } catch (e) {
      if (attempt === 4) return { query, ok: false, error: String(e) };
      await sleep(2 ** attempt * 1000); // exponential backoff
    }
  }
}

// process in waves of `concurrency` to cap in-flight requests
async function batchSearch(queries, options = {}, concurrency = 20) {
  const out = [];
  for (let i = 0; i < queries.length; i += concurrency) {
    const wave = queries.slice(i, i + concurrency);
    out.push(...(await Promise.all(wave.map((q) => searchOne(q, options)))));
  }
  return out;
}

const results = await batchSearch(queries, { searchDepth: "advanced" });
```

Size concurrency from your own [rate limit](https://docs.tavily.com/documentation/rate-limits.md): `concurrency ≈ (RPM / 60) × avg_latency_s`. For example, at 100 RPM and 3s avg latency that's `(100 / 60) × 3 ≈ 5`. Start there and tune up while watching your `429` rate.

### Deduplication

Dedupe the results to save tokens and avoid repetitive context — join unique `content` chunks with Tavily's `[...]` separator.

```python Python theme={null}
def dedupe(results):
    merged = {}
    for r in results:
        if not r["ok"]:
            continue
        for item in r["data"]["results"]:
            url = item["url"].split("?")[0].rstrip("/")  # canonicalize
            e = merged.setdefault(url, {"url": url, "score": 0, "chunks": []})
            e["score"] = max(e["score"], item.get("score", 0))
            for c in item.get("content", "").split("[...]"):
                if (c := c.strip()) and c not in e["chunks"]:
                    e["chunks"].append(c)
    return sorted(
        ({"url": e["url"], "score": e["score"], "content": " [...] ".join(e["chunks"])}
         for e in merged.values()),
        key=lambda x: x["score"], reverse=True,
    )

corpus = dedupe(results)  # dedupe the batch results from above
```

```javascript JavaScript theme={null}
function dedupe(results) {
  const merged = new Map();
  for (const r of results) {
    if (!r.ok) continue;
    for (const item of r.data.results) {
      const url = item.url.split("?")[0].replace(/\/+$/, ""); // canonicalize
      const e = merged.get(url) || { url, score: 0, chunks: [] };
      e.score = Math.max(e.score, item.score ?? 0);
      for (const c of (item.content || "").split("[...]")) {
        const t = c.trim();
        if (t && !e.chunks.includes(t)) e.chunks.push(t);
      }
      merged.set(url, e);
    }
  }
  return [...merged.values()]
    .map((e) => ({ url: e.url, score: e.score, content: e.chunks.join(" [...] ") }))
    .sort((a, b) => b.score - a.score);
}

const corpus = dedupe(results); // dedupe the batch results from above
```

### Operational checklist

* **Run queries in parallel, but cap how many run at once** with a semaphore so you stay under your rate limit.
* **Handle failures per query.** Tag each result `ok` / `error` and retry only the failed ones with backoff, so a single error never sinks the whole batch.
* **Consolidate results.** Dedupe URLs and combine their unique content so you don't pay to process the same page twice.
* **Track credits.** Pass `include_usage=True` and sum the `usage` from each response to see total credits spent across the batch.
* **Set a timeout.** Cap each search (e.g. `timeout=10`) so one slow query doesn't stall the batch.

## Post-Processing

### Using metadata

Leverage response metadata to refine results:

| Field | Use case |
| - | - |
| `score` | Filter/rank by relevance score |
| `title` | Keyword filtering on headlines |
| `content` | Quick relevance check |
| `raw_content` | Deep analysis and regex extraction |

### Score-based filtering

The `score` indicates relevance between query and content. Higher is better, but the ideal threshold depends on your use case.

```python theme={null}
# Filter results with score > 0.7
filtered = [r for r in results if r['score'] > 0.7]
```

### Regex extraction

Extract structured data from `raw_content`:

```python theme={null}
import re

# Extract location
text = "Company: Tavily, Location: New York"
match = re.search(r"Location: (\w+)", text)
location = match.group(1) if match else None  # "New York"

# Extract all emails
text = "Contact: john@example.com, support@tavily.com"
emails = re.findall(r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}", text)
```

## Use Session Tracking for Multi-Step Workflows

When an agent issues several Tavily calls to answer a single user task — for example, retrieving sources, then extracting full content from a subset, then running follow-up searches — pass a **consistent `session_id` across all related calls**.

If your agent serves multiple end-users behind a single API key, also pass a stable `human_id` per user. For security, Tavily hashes human IDs before processing or storing them.

See the [SDK references](https://docs.tavily.com/sdk/python/reference.md#session-tracking) or the [API HTTP headers](https://docs.tavily.com/documentation/api-headers.md#session-tracking) for how to set these.
