0
# Tavily Python
1

2
A comprehensive Python wrapper for the Tavily API that enables intelligent web search, content extraction, web crawling, and website mapping capabilities. Designed for seamless integration into AI applications, RAG systems, and research tools with built-in error handling and support for both synchronous and asynchronous operations.
3

4
## Package Information
5

6
- **Package Name**: tavily-python
7
- **Language**: Python
8
- **Installation**: `pip install tavily-python`
9
- **Requirements**: Python ≥3.6
10

11
## Core Imports
12

13
```python
14
from tavily import TavilyClient, AsyncTavilyClient
15
```
16

17
**Note**: The legacy `Client` class is also available but deprecated. Use `TavilyClient` instead:
18

19
```python
20
from tavily import Client  # Deprecated - use TavilyClient instead
21
```
22

23
For error handling:
24

25
```python
26
from tavily import (
27
    TavilyClient,
28
    InvalidAPIKeyError,
29
    UsageLimitExceededError,
30
    MissingAPIKeyError,
31
    BadRequestError
32
)
33
```
34

35
Additional error types are available directly from the errors module (used internally by the client):
36

37
```python
38
from tavily.errors import ForbiddenError, TimeoutError
39
```
40

41
**Note**: `ForbiddenError` and `TimeoutError` are internal exception classes used by the client but not exported in the main package. They can be imported directly from the errors module if needed for advanced error handling.
42

43
For hybrid RAG functionality:
44

45
```python
46
from tavily import TavilyHybridClient
47
```
48

49
## Basic Usage
50

51
```python
52
from tavily import TavilyClient
53

54
# Initialize client with API key
55
client = TavilyClient(api_key="tvly-YOUR_API_KEY")
56

57
# Perform a basic search
58
response = client.search("What is machine learning?")
59
print(response)
60

61
# Get search context for RAG applications
62
context = client.get_search_context(
63
    query="Latest developments in AI",
64
    max_tokens=4000
65
)
66

67
# Extract content from URLs
68
content = client.extract(["https://example.com/article"])
69

70
# Crawl a website
71
crawl_results = client.crawl(
72
    "https://docs.python.org",
73
    max_depth=2,
74
    limit=10
75
)
76
```
77

78
## Architecture
79

80
The Tavily Python wrapper is built around several key components:
81

82
- **Client Classes**: Synchronous (`TavilyClient`) and asynchronous (`AsyncTavilyClient`) API clients
83
- **Hybrid RAG**: Integration with vector databases for combined local and web search
84
- **Error Handling**: Comprehensive exception hierarchy for robust error management
85
- **Token Management**: Utilities for managing response sizes and token limits
86
- **Proxy Support**: Built-in support for HTTP/HTTPS proxies
87

88
This design enables flexible integration patterns while maintaining simplicity for basic use cases and power for advanced applications.
89

90
## Capabilities
91

92
### Web Search Operations
93

94
Comprehensive web search functionality including basic and advanced search modes, topic-focused searches, time-constrained queries, and specialized Q&A and company information searches.
95

96
```python { .api }
97
def search(
98
    query: str,
99
    search_depth: Literal["basic", "advanced"] = None,
100
    topic: Literal["general", "news", "finance"] = None,
101
    max_results: int = None,
102
    **kwargs
103
) -> dict: ...
104

105
def get_search_context(
106
    query: str,
107
    max_tokens: int = 4000,
108
    **kwargs
109
) -> str: ...
110

111
def qna_search(
112
    query: str,
113
    search_depth: Literal["basic", "advanced"] = "advanced",
114
    **kwargs
115
) -> str: ...
116
```
117

118
[Search Operations](./search.md)
119

120
### Content Extraction and Web Crawling
121

122
Extract content from individual URLs or crawl entire websites with intelligent navigation, content filtering, and structured data extraction capabilities.
123

124
```python { .api }
125
def extract(
126
    urls: Union[List[str], str],
127
    extract_depth: Literal["basic", "advanced"] = None,
128
    format: Literal["markdown", "text"] = None,
129
    **kwargs
130
) -> dict: ...
131

132
def crawl(
133
    url: str,
134
    max_depth: int = None,
135
    max_breadth: int = None,
136
    instructions: str = None,
137
    **kwargs
138
) -> dict: ...
139
```
140

141
[Content Operations](./content.md)
142

143
### Website Structure Mapping
144

145
Discover and map website structures without extracting full content, useful for understanding site architecture and finding relevant pages before detailed crawling.
146

147
```python { .api }
148
def map(
149
    url: str,
150
    max_depth: int = None,
151
    max_breadth: int = None,
152
    instructions: str = None,
153
    **kwargs
154
) -> dict: ...
155
```
156

157
[Website Mapping](./mapping.md)
158

159
### Asynchronous Operations
160

161
Full async/await support for all API operations, enabling high-performance concurrent requests and integration with async frameworks.
162

163
```python { .api }
164
class AsyncTavilyClient:
165
    async def search(self, query: str, **kwargs) -> dict: ...
166
    async def extract(self, urls: Union[List[str], str], **kwargs) -> dict: ...
167
    async def crawl(self, url: str, **kwargs) -> dict: ...
168
    async def map(self, url: str, **kwargs) -> dict: ...
169
```
170

171
[Async Operations](./async.md)
172

173
### Hybrid RAG Integration
174

175
Combine Tavily's web search capabilities with local vector database searches for enhanced RAG applications, supporting MongoDB with custom embedding and ranking functions.
176

177
```python { .api }
178
class TavilyHybridClient:
179
    def __init__(
180
        self,
181
        api_key: str,
182
        db_provider: Literal['mongodb'],
183
        collection,
184
        index: str,
185
        **kwargs
186
    ): ...
187
    
188
    def search(
189
        self,
190
        query: str,
191
        max_results: int = 10,
192
        save_foreign: bool = False,
193
        **kwargs
194
    ) -> list: ...
195
```
196

197
[Hybrid RAG](./hybrid-rag.md)
198

199
## Error Handling
200

201
All API operations can raise specific exceptions for different error conditions:
202

203
```python { .api }
204
class InvalidAPIKeyError(Exception): ...
205
class UsageLimitExceededError(Exception): ...
206
class MissingAPIKeyError(Exception): ...
207
class BadRequestError(Exception): ...
208
class ForbiddenError(Exception): ...
209
class TimeoutError(Exception): ...
210
```
211

212
Handle errors appropriately in your applications:
213

214
```python
215
from tavily import TavilyClient, InvalidAPIKeyError, UsageLimitExceededError, BadRequestError
216
from tavily.errors import ForbiddenError, TimeoutError
217

218
client = TavilyClient(api_key="your-key")
219

220
try:
221
    results = client.search("your query")
222
except InvalidAPIKeyError:
223
    print("Invalid API key provided")
224
except UsageLimitExceededError:
225
    print("API usage limit exceeded")
226
except ForbiddenError:
227
    print("Access forbidden")
228
except TimeoutError as e:
229
    print(f"Request timed out after {e.timeout} seconds")
230
except BadRequestError as e:
231
    print(f"Bad request: {e}")
232
except Exception as e:
233
    print(f"Unexpected error: {e}")
234
```
235

236
## Types
237

238
```python { .api }
239
# Type aliases for parameter constraints
240
SearchDepth = Literal["basic", "advanced"]
241
Topic = Literal["general", "news", "finance"]
242
TimeRange = Literal["day", "week", "month", "year"]
243
ExtractDepth = Literal["basic", "advanced"]
244
ContentFormat = Literal["markdown", "text"]
245
AnswerMode = Union[bool, Literal["basic", "advanced"]]
246
RawContentMode = Union[bool, Literal["markdown", "text"]]
247

248
# Common parameter types
249
Domains = Sequence[str]
250
Paths = Sequence[str]
251
```