1---
2name: tavily-best-practices
3description: "Build production-ready Tavily integrations with best practices baked in. Reference documentation for developers using coding assistants (Claude Code, Cursor, etc.) to implement web search, content extraction, crawling, and research in agentic workflows, RAG systems, or autonomous agents."
4---
5 
6# Tavily
7 
8Tavily is a search API designed for LLMs, enabling AI applications to access real-time web data.
9 
10## Installation
11 
12**Python:**
13```bash
14pip install tavily-python
15```
16 
17**JavaScript:**
18```bash
19npm install @tavily/core
20```
21 
22See **[references/sdk.md](references/sdk.md)** for complete SDK reference.
23 
24## Client Initialization
25 
26```python
27from tavily import TavilyClient
28 
29# Uses TAVILY_API_KEY env var (recommended)
30client = TavilyClient()
31 
32#With project tracking (for usage organization)
33client = TavilyClient(project_id="your-project-id")
34 
35# Async client for parallel queries
36from tavily import AsyncTavilyClient
37async_client = AsyncTavilyClient()
38```
39 
40## Choosing the Right Method
41 
42**For custom agents/workflows:**
43 
44| Need | Method |
45|------|--------|
46| Web search results | `search()` |
47| Content from specific URLs | `extract()` |
48| Content from entire site | `crawl()` |
49| URL discovery from site | `map()` |
50 
51**For out-of-the-box research:**
52 
53| Need | Method |
54|------|--------|
55| End-to-end research with AI synthesis | `research()` |
56 
57## Quick Reference
58 
59### search() - Web Search
60 
61```python
62response = client.search(
63    query="quantum computing breakthroughs",  # Keep under 400 chars
64    max_results=10,
65    search_depth="advanced"
66)
67print(response)
68```
69Key parameters: `query`, `max_results`, `search_depth` (ultra-fast/fast/basic/advanced), `include_domains`, `exclude_domains`, `time_range`
70 
71See **[references/search.md](references/search.md)** for complete search reference.
72 
73### extract() - URL Content Extraction
74 
75```python
76# Simple one-step extraction
77response = client.extract(
78    urls=["https://docs.example.com"],
79    extract_depth="advanced"
80)
81print(response)
82```
83Key parameters: `urls` (max 20), `extract_depth`, `query`, `chunks_per_source` (1-5)
84 
85See **[references/extract.md](references/extract.md)** for complete extract reference.
86 
87### crawl() - Site-Wide Extraction
88 
89```python
90response = client.crawl(
91    url="https://docs.example.com",
92    instructions="Find API documentation pages",  # Semantic focus
93    extract_depth="advanced"
94)
95print(response)
96```
97Key parameters: `url`, `max_depth`, `max_breadth`, `limit`, `instructions`, `chunks_per_source`, `select_paths`, `exclude_paths`
98 
99See **[references/crawl.md](references/crawl.md)** for complete crawl reference.
100 
101### map() - URL Discovery
102 
103```python
104response = client.map(
105    url="https://docs.example.com"
106)
107print(response)
108```
109 
110### research() - AI-Powered Research
111 
112```python
113import time
114 
115# For comprehensive multi-topic research
116result = client.research(
117    input="Analyze competitive landscape for X in SMB market",
118    model="pro"  # or "mini" for focused queries, "auto" when unsure
119)
120request_id = result["request_id"]
121 
122# Poll until completed
123response = client.get_research(request_id)
124while response["status"] not in ["completed", "failed"]:
125    time.sleep(10)
126    response = client.get_research(request_id)
127 
128print(response["content"])  # The research report
129```
130 
131Key parameters: `input`, `model` ("mini"/"pro"/"auto"), `stream`, `output_schema`, `citation_format`
132 
133See **[references/research.md](references/research.md)** for complete research reference.
134 
135## Detailed Guides
136 
137For complete parameters, response fields, patterns, and examples:
138 
139- **[references/sdk.md](references/sdk.md)** - Python & JavaScript SDK reference, async patterns, Hybrid RAG
140- **[references/search.md](references/search.md)** - Query optimization, search depth selection, domain filtering, async patterns, post-filtering
141- **[references/extract.md](references/extract.md)** - One-step vs two-step extraction, query/chunks for targeting, advanced mode
142- **[references/crawl.md](references/crawl.md)** - Crawl vs Map, instructions for semantic focus, use cases, Map-then-Extract pattern
143- **[references/research.md](references/research.md)** - Prompting best practices, model selection, streaming, structured output schemas
144- **[references/integrations.md](references/integrations.md)** - LangChain, LlamaIndex, CrewAI, Vercel AI SDK, and framework integrations
145