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:
Show Latency vs relevance chart
This chart is a heuristic and is not to scale. Depth Latency Relevance Content Type ultra-fastLowest Lower Content fastLow Good Chunks basicMedium High Content advancedHigher 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.
Fast + Ultra-Fast Depth When 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 Parameter Description 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 Parameter Description 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_resultsLimits results returned (default: 5). Setting too high may return lower-quality results.
include_raw_contentReturns full extracted page content. For comprehensive extraction, consider a two-step process:
Search to retrieve relevant URLs
Use Extract API to get content
auto_parametersTavily 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.
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 Leverage response metadata to refine results:
Field Use 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 ]
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: [email protected] , [email protected] " emails = re.findall( r " [ a-zA-Z0-9._%+- ] + @ [ a-zA-Z0-9.- ] + \. [ a-zA-Z ] {2,} " , text)
