Skip to main content

​
What You’ll Learn

  • Running a basic web search and reading results
  • Filtering by recency and news sources
  • Constraining searches to specific domains
  • Aggregating results across multiple queries with async

​
How Does It Work?

Tavily Search returns relevant web results for a natural-language query, optimized for LLM consumption. Each result includes a title, URL, relevance score, and a content snippet. You can tune the depth/speed tradeoff, filter by topic or time range, and restrict results to specific domains.

​
Getting Started

Get your Tavily API key

1

Install the Tavily Python SDK

uv venv
uv pip install tavily-python
2

Run a search

import os
from tavily import TavilyClient

client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

response = client.search(
    query="What are the latest breakthroughs in quantum computing?",
    max_results=5,
)

for result in response["results"]:
    print(f"[{result['score']:.2f}] {result['title']}")
    print(f"  {result['url']}\n")
3

Output

[0.92] Quantum Computing Breakthroughs in 2025 - Nature
  https://nature.com/articles/quantum-2025

[0.87] Google Achieves New Quantum Milestone
  https://blog.google/technology/quantum/milestone-2025/

[0.81] IBM Roadmap: 100K Qubits by 2033
  https://research.ibm.com/blog/quantum-roadmap
...
Restrict results to trusted sources with include_domains, or remove noise with exclude_domains. 
response = client.search(
    query="CEO background at Apple",
    include_domains=["apple.com"],
    max_results=5,
)

for result in response["results"]:
    print(f"{result['title']}: {result['url']}")
You can also combine domain filters with exclusions: 
response = client.search(
    query="enterprise AI platforms comparison",
    include_domains=["medium.com"],
    exclude_domains=["reddit.com", "quora.com"],
    search_depth="advanced",
)
See this pattern in action in the Product News Tracker tutorial.

​
Multi-Query Aggregation

For complex search operations, run multiple focused queries concurrently with AsyncTavilyClient and merge the results. 
import os
import asyncio
from tavily import AsyncTavilyClient

async def multi_query_search():
    client = AsyncTavilyClient(api_key=os.environ["TAVILY_API_KEY"])

    queries = [
        "Competitors of Notion in the productivity space",
        "Notion financial performance and funding",
        "Recent Notion product launches and AI features",
    ]

    responses = await asyncio.gather(
        *(client.search(q, max_results=5) for q in queries),
        return_exceptions=True,
    )

    all_results = []
    for query, resp in zip(queries, responses):
        if isinstance(resp, Exception):
            print(f"Failed: {query} — {resp}")
            continue
        for r in resp["results"]:
            r["source_query"] = query
            all_results.append(r)

    seen = set()
    unique = []
    for r in sorted(all_results, key=lambda x: x["score"], reverse=True):
        if r["url"] not in seen:
            seen.add(r["url"])
            unique.append(r)

    return unique

results = asyncio.run(multi_query_search())
for r in results[:10]:
    print(f"[{r['score']:.2f}] {r['title']}")
Breaking a broad question into 2-3 focused sub-queries often produces better results than a single long query.

​
Critical Knobs

  • Default: "basic"
  • "advanced" — highest relevance, reranked chunks (2 credits)
  • "fast" — lower latency, chunk format (1 credit)
  • "ultra-fast" — near-instant, summary format (0.5 credits)
  • time_range — relative filter: "day", "week", "month", "year"
  • start_date / end_date — absolute date range in YYYY-MM-DD format
  • Use one or the other, not both
  • Restrict results to specific domains or filter them out
  • Keep lists short for best results
  • Range: 1–20, default: 5
  • Higher values may return lower-quality results
For the complete parameter list, see the Search API reference.

​
Production Notes

  • Credits:
    • "basic", "fast", and "ultra-fast" cost 1 credit per query.
    • "advanced" costs 2 credits per query.
  • Rate limits: See Rate Limits for current thresholds.
  • Quality filtering: Use score from the response to filter low-relevance results (e.g., discard results below 0.5).
  • Async for throughput: Use AsyncTavilyClient with asyncio.gather when making multiple concurrent requests.

​
Next Steps

Search API Reference

Full parameter list, response schema, and interactive playground.

Search Best Practices

Query optimization, depth selection, filtering, and post-processing tips.

Python SDK Reference

Python client methods, async support, and type details.

JavaScript SDK Reference

JavaScript/TypeScript client methods and usage.