Files

5.1 KiB

Tavily API Reference

Overview

Tavily is a search engine optimized for Large Language Models (LLMs) and AI applications. It provides:

  • AI-optimized results: Results specifically formatted for LLM consumption
  • Answer generation: Optional AI-generated summaries from search results
  • Raw content extraction: Clean, parsed HTML content from sources
  • Domain filtering: Include or exclude specific domains
  • Image search: Relevant images for visual context
  • Topic specialization: General or news-focused search

API Key Setup

  1. Visit https://tavily.com and sign up
  2. Generate an API key from your dashboard
  3. Store the key securely:
    • Recommended: Add to Bot config under skills.entries.tavily.apiKey
    • Alternative: Set TAVILY_API_KEY environment variable

Search Parameters

Required

  • query (string): The search query

Optional

Parameter Type Default Description
search_depth string "basic" "basic" (fast, ~1-2s) or "advanced" (comprehensive, ~5-10s)
topic string "general" "general" or "news" (current events, last 7 days)
max_results int 5 Number of results (1-10)
include_answer bool true Include AI-generated answer summary
include_raw_content bool false Include cleaned HTML content of sources
include_images bool false Include relevant images
include_domains list[str] null Only search these domains
exclude_domains list[str] null Exclude these domains

Response Format

{
  "success": true,
  "query": "What is quantum computing?",
  "answer": "Quantum computing is a type of computing that uses...",
  "results": [
    {
      "title": "Quantum Computing Explained",
      "url": "https://example.com/quantum",
      "content": "Quantum computing leverages...",
      "score": 0.95,
      "raw_content": null
    }
  ],
  "images": ["https://example.com/image.jpg"],
  "response_time": "1.67",
  "usage": {
    "credits": 1
  }
}

Use Cases & Best Practices

When to Use Tavily

  1. Research tasks: Comprehensive information gathering
  2. Current events: News-focused queries with topic="news"
  3. Domain-specific search: Use include_domains for trusted sources
  4. Visual content: Enable include_images for visual context
  5. LLM consumption: Results are pre-formatted for AI processing

Search Depth Comparison

Depth Speed Results Quality Use Case
basic 1-2s Good Quick lookups, simple facts
advanced 5-10s Excellent Research, complex topics, comprehensive analysis

Recommendation: Start with basic, use advanced for research tasks.

Domain Filtering

Include domains (allowlist):

include_domains=["python.org", "github.com", "stackoverflow.com"]

Only search these specific domains - useful for trusted sources.

Exclude domains (denylist):

exclude_domains=["pinterest.com", "quora.com"]

Remove unwanted or low-quality sources.

Topic Selection

General (topic="general"):

  • Default mode
  • Broader web search
  • Historical and evergreen content
  • Best for most queries

News (topic="news"):

  • Last 7 days only
  • News-focused sources
  • Current events and developments
  • Best for "latest", "recent", "current" queries

Cost & Rate Limits

  • Credits: Each search consumes credits (1 credit for basic search)
  • Free tier: Check https://tavily.com/pricing for current limits
  • Rate limits: Varies by plan tier

Error Handling

Common errors:

  1. Missing API key

    {
      "error": "Tavily API key required",
      "setup_instructions": "Set TAVILY_API_KEY environment variable"
    }
    
  2. Package not installed

    {
      "error": "tavily-python package not installed",
      "install_command": "pip install tavily-python"
    }
    
  3. Invalid API key

    {
      "error": "Invalid API key"
    }
    
  4. Rate limit exceeded

    {
      "error": "Rate limit exceeded"
    }
    

Python SDK

The skill uses the official tavily-python package:

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-...")
response = client.search(
    query="What is AI?",
    search_depth="advanced",
    max_results=10
)

Install: pip install tavily-python

Comparison with Other Search APIs

Feature Tavily Brave Search Perplexity
AI Answer ✅ Yes ❌ No ✅ Yes
Raw Content ✅ Yes ❌ No ❌ No
Domain Filtering ✅ Yes Limited ❌ No
Image Search ✅ Yes ✅ Yes ❌ No
News Mode ✅ Yes ✅ Yes ✅ Yes
LLM Optimized ✅ Yes ❌ No ✅ Yes
Speed Medium Fast Medium
Free Tier ✅ Yes ✅ Yes Limited

Additional Resources