Tavily is a specialized search API designed specifically for LLMs, enabling developers to build AI applications that can access real-time, accurate web data. Let's use the Python SDK to build with tavily.

Prerequisites

Tavily API Key Required - Get your key at https://tavily.com

Add to ~/.claude/settings.json:

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  }
}

Restart Claude Code after adding your API key.

Tavily Python SDK

Installation

pip install tavily-python

Client Initialization

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# Or use environment variable TAVILY_API_KEY
client = TavilyClient()

Async client:

The async client enables parallel query execution, ideal for agentic workflows that need to gather information quickly before passing it to a model for analysis.

from tavily import AsyncTavilyClient

async_client = AsyncTavilyClient(api_key="tvly-YOUR_API_KEY")

Available Endpoints

Endpoint	Purpose	Use Case
search()	Web search	real time data retrieval from the web
extract()	Scrape content from URLs	Page content extraction
crawl() and map()	Traverse website structures and simultaneously scrape pages	Documentation, site-wide extraction
research	Out of the box research agent	ready-to-use iterative research

Choosing the Right Method

If you are building a custom agent or agentic workflow:

Need	Method
Web search results	search()
Content from specific URLs	extract()
Content from an entire site	crawl()
URL discovery from a site	map()

These methods give you full control but require additional work: data processing, LLM integration, and workflow orchestration.

If you want an out-of-the-box solution:

Need	Method
End-to-end research with AI synthesis and built-in context engineering	research()

The research endpoint provides faster time-to-value with AI-synthesized insights, but offers less flexibility than building custom workflows.

Detailed Guides

For detailed usage instructions, parameters, patterns, and best practices:

• references/search.md — Query optimization, filtering, async patterns, post-filtering strategies (regex + LLM verification)
• references/extract.md — One-step vs two-step extraction, advanced mode, research pipelines
• references/crawl.md — Crawl vs Map, depth/breadth control, path patterns, performance optimization
• references/research.md — Usage, Streaming, structured output, polling