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

tavily-best-practices