Skip to main content

​
Query Optimization

​
Keep your query under 400 characters

Keep queries concise—under 400 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: 
// 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:
DepthLatencyRelevanceContent Type
ultra-fastLowestLowerContent
fastLowGoodChunks
basicMediumHighContent
advancedHigherHighestChunks

​
Content types

TypeDescription
ContentNLP-based summary of the page, providing general context
ChunksShort 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.

​
Fast + Ultra-Fast

DepthWhen to use
ultra-fastWhen latency is absolutely crucial. Delivers near-instant results, prioritizing speed over relevance. Ideal for real-time applications where response time is critical.
fastWhen latency is more important than relevance, but you want results in reranked chunks format. Good for applications that need quick, targeted snippets.
basicA solid balance between relevance and latency. Best for general-purpose searches where you need quality results without the overhead of advanced processing.
advancedWhen 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: 
{
  "query": "How many countries use Monday.com?",
  "search_depth": "advanced",
  "chunks_per_source": 3,
  "include_raw_content": true
}

​
Filtering Results

​
By date

ParameterDescription
time_rangeFilter by relative time: day, week, month, year
start_date / end_dateFilter by specific date range (format: YYYY-MM-DD)
{ "query": "latest ML trends", "time_range": "month" }
{ "query": "AI news", "start_date": "2025-01-01", "end_date": "2025-02-01" }

​
By topic

Use topic to filter by content type. Set to news for news sources (includes published_date metadata): 
{ "query": "What happened today in NY?", "topic": "news" }

​
By domain

ParameterDescription
include_domainsLimit to specific domains
exclude_domainsFilter out specific domains
countryBoost results from a specific country
// Restrict to LinkedIn profiles
{ "query": "CEO background at Google", "include_domains": ["linkedin.com/in"] }

// 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"] }
Keep domain lists short and relevant for best results.

​
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 to get content

​
auto_parameters

Tavily automatically configures parameters based on query intent. Your explicit values override automatic ones. 
{
  "query": "impact of AI in education policy",
  "auto_parameters": true,
  "search_depth": "basic" // Override to control cost
}
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: 
{
  "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 & Performance

Use async calls for concurrent requests: 
import asyncio
from tavily import AsyncTavilyClient

tavily_client = AsyncTavilyClient("tvly-YOUR_API_KEY")

async def fetch_and_gather():
    queries = ["latest AI trends", "future of quantum computing"]
    responses = await asyncio.gather(
        *(tavily_client.search(q) for q in queries),
        return_exceptions=True
    )
    for response in responses:
        if isinstance(response, Exception):
            print(f"Failed: {response}")
        else:
            print(response)

asyncio.run(fetch_and_gather())

​
Post-Processing

​
Using metadata

Leverage response metadata to refine results:
FieldUse case
scoreFilter/rank by relevance score
titleKeyword filtering on headlines
contentQuick relevance check
raw_contentDeep 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. 
# 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: 
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)