Tavily Best Practices

Tavily is an AI-native search engine optimized for LLMs and AI agents. It provides 5 core APIs: Search, Extract, Crawl, Map, and Research.

Quick Reference

API Endpoint Purpose Cost

Search POST /search

Web search with relevance scoring 1-2 credits

Extract POST /extract

Content extraction from specific URLs 1-2 credits/5 URLs

Crawl POST /crawl

Site traversal + extraction Map + Extract costs

Map POST /map

Site structure discovery (URLs only) 1-2 credits/10 pages

Research POST /research

Multi-agent deep research reports 4-250 credits

Usage GET /usage

Check credit consumption Free

Base URL: https://api.tavily.com

Auth: Authorization: Bearer tvly-YOUR_API_KEY

Setup

Python

pip install tavily-python

JavaScript/TypeScript

npm i @tavily/core

from tavily import TavilyClient client = TavilyClient("tvly-YOUR_API_KEY")

import { tavily } from "@tavily/core"; const client = tavily({ apiKey: "tvly-YOUR_API_KEY" });

For MCP Server setup and API key management, see rules/setup.md.

When to Use Each API

Search — Web search optimized for LLMs

• General web queries needing fresh, relevant results

• News monitoring (topic: "news" )

• Financial data (topic: "finance" )

• Domain-restricted research (include_domains / exclude_domains )

• LLM-generated answers (include_answer: true )

Extract — Content from specific URLs

• You already know which URLs to extract from

• Targeted content retrieval with query-based re-ranking

• Tables, structured data, JS-rendered pages (extract_depth: "advanced" )

Crawl — Site-wide content extraction

• Documentation sites, knowledge bases

• RAG pipeline ingestion

• Multi-page content aggregation

• Deep/nested content discovery

Map — Site structure discovery

• Sitemap generation (URLs only, no content)

• Pre-crawl planning to identify paths

• Domain structure analysis

Research — Multi-agent deep research

• Complex, multi-domain topics requiring synthesis

• Company research, competitive analysis

• Structured output for data pipelines (output_schema )

Detailed References

Load these files on demand when you need specific API details:

API Reference (parameters, responses, examples)

• references/api-search.md — Search API complete reference

• references/api-extract.md — Extract API complete reference

• references/api-crawl.md — Crawl API complete reference

• references/api-map.md — Map API complete reference

• references/api-research.md — Research API complete reference

SDK References

• references/sdk-python.md — Python SDK (sync + async clients, all methods)

• references/sdk-javascript.md — JavaScript SDK (all methods, camelCase params)

Best Practices & Rules

• rules/best-practices-search.md — Query optimization, search depth, filtering, async

• rules/best-practices-extract.md — Extraction approaches, pipelines, filtering

• rules/best-practices-crawl.md — Crawl vs Map, depth/breadth tuning, use cases

• rules/best-practices-research.md — Prompting, model selection, structured output

• rules/setup.md — Installation, API key management, MCP server, integrations

Integrations

• references/integrations.md — LangChain, LlamaIndex, CrewAI, OpenAI, Anthropic, Vercel AI SDK, MCP Server

Essential Patterns

1. Basic Search

response = client.search( query="What is quantum computing?", search_depth="basic", max_results=5 ) for result in response["results"]: print(f"{result['title']}: {result['url']} (score: {result['score']})")

2. Advanced Search with Chunks

response = client.search( query="How many countries use Monday.com?", search_depth="advanced", chunks_per_source=3, include_raw_content=True )

3. News Search with Date Filtering

response = client.search( query="AI regulation updates", topic="news", time_range="week", max_results=10 )

4. Search → Extract Pipeline

Step 1: Find relevant URLs

search_results = client.search( query="AI healthcare applications", search_depth="advanced", max_results=20 )

Step 2: Filter by relevance score

urls = [r["url"] for r in search_results["results"] if r["score"] > 0.5]

Step 3: Extract focused content

extracted = client.extract( urls=urls[:10], query="diagnostic AI tools accuracy", chunks_per_source=3 )

5. Focused Crawl with Instructions

response = client.crawl( url="docs.example.com", instructions="Find all pages about authentication", max_depth=2, max_breadth=50, limit=100, select_paths=["/docs/.", "/guides/."], chunks_per_source=3 )

6. Map → Crawl Workflow

Step 1: Discover site structure

site_map = client.map( url="docs.example.com", max_depth=2, select_paths=["/api/.*"] ) print(f"Found {len(site_map['results'])} URLs")

Step 2: Crawl discovered paths

content = client.crawl( url="docs.example.com", select_paths=["/api/.*"], max_depth=2, extract_depth="advanced" )

7. Research with Structured Output

response = client.research( query="Competitive analysis of Notion in 2026", model="pro", output_schema={ "properties": { "company": {"type": "string", "description": "Company name"}, "competitors": {"type": "array", "items": {"type": "string"}}, "market_position": {"type": "string", "description": "Current market standing"} }, "required": ["company", "competitors"] } )

8. Async Parallel Searches

import asyncio from tavily import AsyncTavilyClient

client = AsyncTavilyClient("tvly-YOUR_API_KEY")

async def parallel_search(): queries = ["AI trends 2026", "quantum computing advances", "LLM benchmarks"] responses = await asyncio.gather( *(client.search(q) for q in queries), return_exceptions=True ) return [r for r in responses if not isinstance(r, Exception)]

results = asyncio.run(parallel_search())

Credits & Pricing

API Level Cost

Search basic / fast / ultra-fast

1 credit

Search advanced

2 credits

Extract basic

1 credit / 5 URLs

Extract advanced

2 credits / 5 URLs

Map without instructions

1 credit / 10 pages

Map with instructions

2 credits / 10 pages

Crawl Mapping + Extraction combined See Map + Extract

Research mini

4-110 credits

Research pro

15-250 credits

Plan Credits/month Price

Researcher (free) 1,000 Free

Project 4,000 $30/mo

Bootstrap 15,000 $100/mo

Startup 38,000 $220/mo

Growth 100,000 $500/mo

Pay-as-you-go — $0.008/credit

Rate Limits: 100 RPM (dev) / 1,000 RPM (prod) for Search/Extract. Crawl: 100 RPM. Research: 20 RPM.

Key Decision Matrix

Need Use Why

Quick web search Search (basic ) 1 credit, fast, NLP summary

Precise snippets Search (advanced ) Reranked chunks, highest relevance

Real-time news Search (topic: "news" ) News-optimized agent

Content from known URLs Extract Direct URL → content

Full site content Crawl Traversal + extraction

Site structure only Map URLs only, fast, cheap

Deep research report Research (pro ) Multi-agent synthesis

Quick focused research Research (mini ) Efficient, narrow scope

Hybrid local + web TavilyHybridClient MongoDB + Tavily combined