---

name: tavily-api-expert description: "Build production-ready Tavily integrations with best practices baked in. Reference documentation for developers using coding assistants (Claude Code, Cursor, etc.) to implement web search, content extraction, crawling, and research in agentic workflows, RAG systems, or autonomous agents."

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:

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

Restart Claude Code after adding your API key.

Tavily Python SDK

Installation

Copypip install tavily-python

Client Initialization

Copyfrom 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.

Copyfrom tavily import AsyncTavilyClient

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

Available Endpoints

Choosing the Right Method

If you are building a custom agent or agentic workflow:

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:

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