1# SDK Reference
2 
3## Table of Contents
4 
5- [Python SDK](#python-sdk)
6- [JavaScript SDK](#javascript-sdk)
7- [Async Patterns](#async-patterns)
8- [Hybrid RAG](#hybrid-rag)
9 
10---
11 
12## Python SDK
13 
14### Installation
15 
16```bash
17pip install tavily-python
18```
19 
20### Client Initialization
21 
22```python
23from tavily import TavilyClient
24 
25# Uses TAVILY_API_KEY env var (recommended)
26client = TavilyClient()
27 
28# Explicit API key
29client = TavilyClient(api_key="tvly-YOUR_API_KEY")
30 
31# With project tracking
32client = TavilyClient(api_key="tvly-YOUR_API_KEY", project_id="your-project-id")
33 
34# With proxies
35proxies = {"http": "<proxy>", "https": "<proxy>"}
36client = TavilyClient(api_key="tvly-YOUR_API_KEY", proxies=proxies)
37```
38 
39### Async Client
40 
41```python
42from tavily import AsyncTavilyClient
43 
44async_client = AsyncTavilyClient()
45 
46# Parallel queries
47import asyncio
48responses = await asyncio.gather(
49    async_client.search("query 1"),
50    async_client.search("query 2"),
51    async_client.search("query 3")
52)
53```
54 
55### Methods
56 
57#### search()
58 
59```python
60response = client.search(
61    query="quantum computing breakthroughs",
62    search_depth="advanced",      # "basic" | "advanced"
63    topic="general",              # "general" | "news" | "finance"
64    max_results=10,               # 0-20
65    include_answer=False,         # bool | "basic" | "advanced"
66    include_raw_content=False,    # bool | "markdown" | "text"
67    include_images=False,
68    time_range="week",            # "day" | "week" | "month" | "year"
69    include_domains=["arxiv.org"],
70    exclude_domains=["reddit.com"],
71    country="united states"
72)
73```
74 
75#### extract()
76 
77```python
78response = client.extract(
79    urls=["https://example.com/page1", "https://example.com/page2"],
80    extract_depth="basic",        # "basic" | "advanced"
81    format="markdown",            # "markdown" | "text"
82    include_images=False,
83    query="focus query",          # Reranks chunks by relevance
84    chunks_per_source=3           # 1-5, requires query
85)
86```
87 
88#### crawl()
89 
90```python
91response = client.crawl(
92    url="https://docs.example.com",
93    max_depth=2,                  # 1-5
94    max_breadth=20,
95    limit=50,
96    instructions="Find API documentation",
97    chunks_per_source=3,          # 1-5, requires instructions
98    select_paths=["/docs/.*"],
99    exclude_paths=["/blog/.*"],
100    extract_depth="basic",
101    format="markdown",
102    allow_external=True
103)
104```
105 
106#### map()
107 
108```python
109response = client.map(
110    url="https://docs.example.com",
111    max_depth=2,
112    max_breadth=20,
113    limit=50,
114    instructions="Find all API pages",
115    select_paths=["/api/.*"],
116    allow_external=False
117)
118```
119 
120#### research()
121 
122```python
123# Start research task
124result = client.research(
125    input="Analyze competitive landscape for X",
126    model="pro",                  # "mini" | "pro" | "auto"
127    stream=False,
128    output_schema=None,           # JSON schema for structured output
129    citation_format="numbered"    # "numbered" | "mla" | "apa" | "chicago"
130)
131 
132# Poll for results
133import time
134response = client.get_research(result["request_id"])
135while response["status"] not in ["completed", "failed"]:
136    time.sleep(10)
137    response = client.get_research(result["request_id"])
138```
139 
140---
141 
142## JavaScript SDK
143 
144### Installation
145 
146```bash
147npm install @tavily/core
148```
149 
150### Client Initialization
151 
152```javascript
153const { tavily } = require("@tavily/core");
154 
155// Basic initialization
156const client = tavily({ apiKey: "tvly-YOUR_API_KEY" });
157 
158// With project tracking
159const client = tavily({
160  apiKey: "tvly-YOUR_API_KEY",
161  projectId: "your-project-id"
162});
163 
164// With proxies
165const client = tavily({
166  apiKey: "tvly-YOUR_API_KEY",
167  proxies: {
168    http: "<proxy>",
169    https: "<proxy>"
170  }
171});
172```
173 
174### Methods
175 
176#### search()
177 
178```javascript
179const response = await client.search("quantum computing", {
180  searchDepth: "advanced",      // "basic" | "advanced"
181  topic: "general",             // "general" | "news" | "finance"
182  maxResults: 10,               // 0-20
183  includeAnswer: false,         // boolean | "basic" | "advanced"
184  includeRawContent: false,     // boolean | "markdown" | "text"
185  includeImages: false,
186  timeRange: "week",            // "day" | "week" | "month" | "year"
187  includeDomains: ["arxiv.org"],
188  excludeDomains: ["reddit.com"],
189  country: "united states"
190});
191```
192 
193#### extract()
194 
195```javascript
196const response = await client.extract([
197  "https://example.com/page1",
198  "https://example.com/page2"
199], {
200  extractDepth: "basic",        // "basic" | "advanced"
201  format: "markdown",           // "markdown" | "text"
202  includeImages: false,
203  query: "focus query"          // Reranks chunks
204});
205```
206 
207#### crawl()
208 
209```javascript
210const response = await client.crawl("https://docs.example.com", {
211  maxDepth: 2,
212  maxBreadth: 20,
213  limit: 50,
214  instructions: "Find API documentation",
215  selectPaths: ["/docs/.*"],
216  excludePaths: ["/blog/.*"],
217  extractDepth: "basic",
218  format: "markdown"
219});
220```
221 
222#### map()
223 
224```javascript
225const response = await client.map("https://docs.example.com", {
226  maxDepth: 2,
227  maxBreadth: 20,
228  limit: 50,
229  instructions: "Find all API pages"
230});
231```
232 
233---
234 
235## Async Patterns
236 
237### Python Parallel Queries
238 
239```python
240import asyncio
241from tavily import AsyncTavilyClient
242 
243client = AsyncTavilyClient()
244 
245async def parallel_search():
246    queries = [
247        "AI trends 2025",
248        "machine learning best practices",
249        "LLM deployment strategies"
250    ]
251 
252    responses = await asyncio.gather(
253        *(client.search(q, search_depth="advanced") for q in queries),
254        return_exceptions=True
255    )
256 
257    for query, response in zip(queries, responses):
258        if isinstance(response, Exception):
259            print(f"Failed: {query}")
260        else:
261            print(f"{query}: {len(response['results'])} results")
262 
263asyncio.run(parallel_search())
264```
265 
266### JavaScript Parallel Queries
267 
268```javascript
269const queries = ["AI trends", "ML practices", "LLM strategies"];
270 
271const responses = await Promise.all(
272  queries.map(q => client.search(q, { searchDepth: "advanced" }))
273);
274 
275responses.forEach((response, i) => {
276  console.log(`${queries[i]}: ${response.results.length} results`);
277});
278```
279 
280---
281 
282## Hybrid RAG
283 
284Combine web search with local database retrieval.
285 
286### Python
287 
288```python
289from tavily import TavilyHybridClient
290from pymongo import MongoClient
291 
292# Connect to MongoDB
293db = MongoClient("mongodb+srv://URI")["DB_NAME"]
294 
295# Initialize hybrid client
296hybrid_client = TavilyHybridClient(
297    api_key="tvly-YOUR_API_KEY",
298    db_provider="mongodb",
299    collection=db.get_collection("documents"),
300    embeddings_field="embeddings",
301    content_field="content"
302)
303 
304# Search across web + local DB
305results = hybrid_client.search(
306    query="quantum computing advances",
307    max_results=10,
308    max_local=5,      # Results from local DB
309    max_foreign=5,    # Results from web
310    save_foreign=True # Store web results in DB
311)
312```
313 
314**Environment Variables:**
315- `TAVILY_PROJECT`: Default project ID
316- `TAVILY_HTTP_PROXY` / `TAVILY_HTTPS_PROXY`: Proxy configuration
317- `CO_API_KEY`: Cohere API key for embeddings
318 
319---
320 
321## Response Structures
322 
323### Search Response
324 
325```python
326{
327    "query": str,
328    "results": [
329        {
330            "title": str,
331            "url": str,
332            "content": str,
333            "score": float,
334            "favicon": str
335        }
336    ],
337    "response_time": float,
338    "request_id": str,
339    "answer": str,      # if include_answer
340    "images": list      # if include_images
341}
342```
343 
344### Extract Response
345 
346```python
347{
348    "results": [
349        {
350            "url": str,
351            "raw_content": str,
352            "images": list,
353            "favicon": str
354        }
355    ],
356    "failed_results": [
357        {"url": str, "error": str}
358    ],
359    "response_time": float,
360    "request_id": str
361}
362```
363 
364### Crawl Response
365 
366```python
367{
368    "base_url": str,
369    "results": [
370        {
371            "url": str,
372            "raw_content": str,
373            "images": list,
374            "favicon": str
375        }
376    ],
377    "response_time": float,
378    "request_id": str
379}
380```
381 
382### Map Response
383 
384```python
385{
386    "base_url": str,
387    "results": [str],  # List of URLs
388    "response_time": float,
389    "request_id": str
390}
391```
392 
393---
394 
395For full API documentation, see:
396- [Python SDK Reference](https://docs.tavily.com/sdk/python/reference)
397- [JavaScript SDK Reference](https://docs.tavily.com/sdk/javascript/reference)
398