0
# Search Operations
1

2
Comprehensive web search functionality with advanced filtering, topic specialization, and optimized output formats for different use cases including RAG applications and Q&A systems.
3

4
## Capabilities
5

6
### General Web Search
7

8
Performs comprehensive web searches with extensive customization options for depth, scope, content inclusion, and result filtering.
9

10
```python { .api }
11
def search(
12
    query: str,
13
    search_depth: Literal["basic", "advanced"] = None,
14
    topic: Literal["general", "news", "finance"] = None,
15
    time_range: Literal["day", "week", "month", "year"] = None,
16
    start_date: str = None,
17
    end_date: str = None,
18
    days: int = None,
19
    max_results: int = None,
20
    include_domains: Sequence[str] = None,
21
    exclude_domains: Sequence[str] = None,
22
    include_answer: Union[bool, Literal["basic", "advanced"]] = None,
23
    include_raw_content: Union[bool, Literal["markdown", "text"]] = None,
24
    include_images: bool = None,
25
    timeout: int = 60,
26
    country: str = None,
27
    auto_parameters: bool = None,
28
    include_favicon: bool = None,
29
    **kwargs
30
) -> dict:
31
    """
32
    Perform a comprehensive web search with extensive customization options.
33

34
    Parameters:
35
    - query: Search query string
36
    - search_depth: Search thoroughness ("basic" for fast results, "advanced" for comprehensive)
37
    - topic: Domain specialization for better results
38
    - time_range: Restrict results to recent timeframe
39
    - start_date/end_date: Custom date range (YYYY-MM-DD format)
40
    - days: Number of days back to search
41
    - max_results: Maximum number of results to return
42
    - include_domains: Only search within these domains
43
    - exclude_domains: Exclude these domains from search
44
    - include_answer: Include AI-generated answer summary
45
    - include_raw_content: Include full page content in specified format
46
    - include_images: Include image URLs in results
47
    - timeout: Request timeout in seconds (max 120)
48
    - country: Geographic search constraint (ISO country code)
49
    - auto_parameters: Enable automatic parameter optimization
50
    - include_favicon: Include website favicon URLs
51

52
    Returns:
53
    Dict containing:
54
    - query: Original search query
55
    - results: List of search result objects
56
    - answer: AI-generated answer (if requested)
57
    - images: List of image URLs (if requested)
58
    - response_time: Query processing time
59
    """
60
```
61

62
**Usage Examples:**
63

64
```python
65
# Basic search
66
results = client.search("climate change impacts")
67

68
# Advanced search with filtering
69
results = client.search(
70
    query="renewable energy trends",
71
    search_depth="advanced",
72
    topic="general",
73
    days=30,
74
    max_results=10,
75
    include_domains=["nature.com", "science.org"],
76
    include_answer="advanced",
77
    include_raw_content="markdown"
78
)
79

80
# News-focused search
81
news_results = client.search(
82
    query="latest AI developments",
83
    topic="news",
84
    time_range="week",
85
    include_images=True
86
)
87
```
88

89
### RAG Context Generation
90

91
Optimized search specifically designed for RAG applications, returning token-limited JSON context suitable for language model consumption.
92

93
```python { .api }
94
def get_search_context(
95
    query: str,
96
    search_depth: Literal["basic", "advanced"] = "basic",
97
    topic: Literal["general", "news", "finance"] = "general",
98
    days: int = 7,
99
    max_results: int = 5,
100
    include_domains: Sequence[str] = None,
101
    exclude_domains: Sequence[str] = None,
102
    max_tokens: int = 4000,
103
    timeout: int = 60,
104
    country: str = None,
105
    include_favicon: bool = None,
106
    **kwargs
107
) -> str:
108
    """
109
    Generate search context optimized for RAG applications.
110

111
    Parameters:
112
    - query: Search query for context generation
113
    - search_depth: Search thoroughness level
114
    - topic: Domain specialization
115
    - days: How many days back to search
116
    - max_results: Maximum search results to process
117
    - include_domains: Only search within these domains
118
    - exclude_domains: Exclude these domains
119
    - max_tokens: Maximum tokens in returned context (based on OpenAI encoding)
120
    - timeout: Request timeout in seconds
121
    - country: Geographic search constraint
122
    - include_favicon: Include favicon URLs
123

124
    Returns:
125
    JSON string containing search context up to token limit with:
126
    - url: Source URL
127
    - content: Relevant content excerpt
128
    """
129
```
130

131
**Usage Examples:**
132

133
```python
134
# Generate context for RAG
135
context = client.get_search_context(
136
    query="What are the benefits of solar energy?",
137
    max_tokens=2000,
138
    days=30
139
)
140

141
# Domain-specific context
142
finance_context = client.get_search_context(
143
    query="stock market trends 2024",
144
    topic="finance",
145
    include_domains=["bloomberg.com", "reuters.com"],
146
    max_tokens=3000
147
)
148
```
149

150
### Question-Answer Search
151

152
Specialized search optimized for direct question answering, returning concise answers rather than raw search results.
153

154
```python { .api }
155
def qna_search(
156
    query: str,
157
    search_depth: Literal["basic", "advanced"] = "advanced",
158
    topic: Literal["general", "news", "finance"] = "general",
159
    days: int = 7,
160
    max_results: int = 5,
161
    include_domains: Sequence[str] = None,
162
    exclude_domains: Sequence[str] = None,
163
    timeout: int = 60,
164
    country: str = None,
165
    include_favicon: bool = None,
166
    **kwargs
167
) -> str:
168
    """
169
    Perform search optimized for question answering.
170

171
    Parameters:
172
    - query: Question to answer
173
    - search_depth: Search thoroughness (defaults to "advanced" for best answers)
174
    - topic: Domain specialization
175
    - days: How many days back to search
176
    - max_results: Maximum results to analyze
177
    - include_domains: Only search within these domains
178
    - exclude_domains: Exclude these domains
179
    - timeout: Request timeout in seconds
180
    - country: Geographic search constraint
181
    - include_favicon: Include favicon URLs
182

183
    Returns:
184
    String containing direct answer to the question
185
    """
186
```
187

188
**Usage Examples:**
189

190
```python
191
# Direct question answering
192
answer = client.qna_search("What is the capital of France?")
193
print(answer)  # "Paris"
194

195
# Complex question with domain focus
196
answer = client.qna_search(
197
    query="How do neural networks learn?",
198
    topic="general",
199
    include_domains=["arxiv.org", "nature.com"]
200
)
201
```
202

203
### Company Information Search
204

205
Specialized search for gathering comprehensive company information by searching across multiple topic areas (news, general, finance) and ranking results by relevance.
206

207
```python { .api }
208
def get_company_info(
209
    query: str,
210
    search_depth: Literal["basic", "advanced"] = "advanced",
211
    max_results: int = 5,
212
    timeout: int = 60,
213
    country: str = None
214
) -> Sequence[dict]:
215
    """
216
    Search for comprehensive company information across multiple domains.
217

218
    Parameters:
219
    - query: Company name or related search term
220
    - search_depth: Search thoroughness level
221
    - max_results: Maximum results to return
222
    - timeout: Request timeout in seconds
223
    - country: Geographic search constraint
224

225
    Returns:
226
    List of search result dictionaries sorted by relevance score, containing:
227
    - title: Result title
228
    - url: Source URL
229
    - content: Content excerpt
230
    - score: Relevance score
231
    """
232
```
233

234
**Usage Examples:**
235

236
```python
237
# Get company information
238
company_info = client.get_company_info("Tesla Inc")
239
for result in company_info:
240
    print(f"Score: {result['score']}")
241
    print(f"Title: {result['title']}")
242
    print(f"URL: {result['url']}")
243
    print(f"Content: {result['content'][:200]}...")
244

245
# Focused company search
246
startup_info = client.get_company_info(
247
    query="OpenAI company",
248
    max_results=3,
249
    country="US"
250
)
251
```
252

253
## Common Parameters Reference
254

255
### Search Depth Options
256
- `"basic"`: Fast search with essential results
257
- `"advanced"`: Comprehensive search with detailed analysis
258

259
### Topic Specialization
260
- `"general"`: Broad web search across all domains
261
- `"news"`: Focus on news and current events
262
- `"finance"`: Financial and business information focus
263

264
### Time Constraints
265
- `time_range`: Predefined ranges ("day", "week", "month", "year")
266
- `start_date`/`end_date`: Custom date range (YYYY-MM-DD)
267
- `days`: Number of days back from current date
268

269
### Content Inclusion
270
- `include_answer`: AI summary (boolean or "basic"/"advanced")
271
- `include_raw_content`: Full page content ("markdown" or "text")
272
- `include_images`: Image URLs in results
273

274
### Domain Filtering
275
- `include_domains`: Whitelist specific domains
276
- `exclude_domains`: Blacklist specific domains
277

278
## Error Handling
279

280
Search operations can raise various exceptions:
281

282
```python
283
from tavily import TavilyClient, InvalidAPIKeyError, UsageLimitExceededError, TimeoutError
284

285
try:
286
    results = client.search("query", timeout=30)
287
except TimeoutError as e:
288
    print(f"Search timed out after {e.timeout} seconds")
289
except UsageLimitExceededError:
290
    print("API usage limit exceeded")
291
except InvalidAPIKeyError:
292
    print("Invalid API key")
293
```