Tavily AI Search

Overview

Tavily is a search engine specifically optimized for Large Language Models and AI applications. Unlike traditional search APIs, Tavily provides AI-ready results with optional answer generation, clean content extraction, and domain filtering capabilities.

Key capabilities:

• - AI-generated answer summaries from search results
• Clean, structured results optimized for LLM processing
• Fast (basic) and comprehensive (advanced) search modes
• Domain filtering (include/exclude specific sources)
• News-focused search for current events
• Image search with relevant visual content
• Raw content extraction for deeper analysis

Architecture

CODEBLOCK0

Quick Start

Basic Search

CODEBLOCK1

Advanced Search

CODEBLOCK2

Domain Filtering

CODEBLOCK3

With Images

CODEBLOCK4

Search Modes

Basic vs Advanced

Decision tree:

1. 1. Need a quick fact or definition? → Use INLINECODE2
2. Researching a complex topic? → Use INLINECODE3
3. Need multiple perspectives? → Use INLINECODE4
4. Time-sensitive query? → Use INLINECODE5

General vs News

Decision tree:

1. 1. Query contains "latest", "recent", "current", "today"? → Use INLINECODE6
2. Looking for historical or evergreen content? → Use INLINECODE7
3. Need up-to-date information? → Use INLINECODE8

API Key Setup

Option 1: Clawdbot Config (Recommended)

Add to your Clawdbot config:

CODEBLOCK5

Access in scripts via Clawdbot's config system.

Option 2: Environment Variable

CODEBLOCK6

Add to ~/.clawdbot/.env or your shell profile.

Getting an API Key

1. 1. Visit https://tavily.com
2. Sign up for an account
3. Navigate to your dashboard
4. Generate an API key (starts with tvly-)
5. Note your plan's rate limits and credit allocation

Common Use Cases

1. Research & Fact-Finding

CODEBLOCK7

2. Current Events

CODEBLOCK8

3. Domain-Specific Research

CODEBLOCK9

4. Visual Research

CODEBLOCK10

5. Content Extraction

CODEBLOCK11

Response Handling

AI Answer

The AI-generated answer provides a concise summary synthesized from search results:

CODEBLOCK12

Use when:

• - Need a quick summary
• Want synthesized information from multiple sources
• Looking for a direct answer to a question

Skip when (--no-answer):

• - Only need source URLs
• Want to form your own synthesis
• Conserving API credits

Structured Results

Each result includes:

• - title: Page title
• INLINECODE13: Source URL
• INLINECODE14: Extracted text snippet
• INLINECODE15: Relevance score (0-1)
• INLINECODE16: Full HTML (if --raw-content enabled)

Images

When --images is enabled, returns URLs of relevant images found during search.

Best Practices

1. Choose the Right Search Depth

• - Start with basic for most queries (faster, cheaper)
• Escalate to advanced only when:

2. Use Domain Filtering Strategically

Include domains for:

• - Academic research (.edu domains)
• Official documentation (official project sites)
• Trusted news sources
• Known authoritative sources

Exclude domains for:

• - Known low-quality content farms
• Irrelevant content types (Pinterest for non-visual queries)
• Sites with paywalls or access restrictions

3. Optimize for Cost

• - Use basic depth as default
• Limit max_results to what you'll actually use
• Disable include_raw_content unless needed
• Cache results locally for repeated queries

4. Handle Errors Gracefully

The script provides helpful error messages:

CODEBLOCK13

Integration Patterns

Programmatic Usage

CODEBLOCK14

JSON Output for Parsing

CODEBLOCK15

Chaining with Other Tools

CODEBLOCK16

Comparison with Other Search APIs

vs Brave Search:

• - ✅ AI answer generation
• ✅ Raw content extraction
• ✅ Better domain filtering
• ❌ Slower than Brave
• ❌ Costs credits

vs Perplexity:

• - ✅ More control over sources
• ✅ Raw content available
• ✅ Dedicated news mode
• ≈ Similar answer quality
• ≈ Similar speed

vs Google Custom Search:

• - ✅ LLM-optimized results
• ✅ Answer generation
• ✅ Simpler API
• ❌ Smaller index
• ≈ Similar cost structure

Troubleshooting

Script Won't Run

CODEBLOCK17

API Key Issues

CODEBLOCK18

Rate Limit Errors

• - Check your plan's credit allocation at https://tavily.com
• Reduce max_results to conserve credits
• Use basic depth instead of INLINECODE27
• Implement local caching for repeated queries

Resources

See api-reference.md for:

• - Complete API parameter documentation
• Response format specifications
• Error handling details
• Cost and rate limit information
• Advanced usage examples

Dependencies

• - Python 3.6+
• INLINECODE28 package (install: pip install tavily-python)
• Valid Tavily API key

Credits & Attribution

• - Tavily API: https://tavily.com
• Python SDK: https://github.com/tavily-ai/tavily-python
• Documentation: https://docs.tavily.com