tavily-search

Tavily Search

Headless web search and content extraction using Tavily. Built for LLM agents — returns clean, summarised results with optional raw article bodies. No browser required.

When to use

• You need up-to-date web information (news, docs, pricing, facts)
• You want cited sources with URLs for a research/writing task
• You need the full readable body of a URL as markdown
• Brave/Google search is not available or rate-limited

When NOT to use

• You already have the page in your context
• The answer is static and likely in the model's training data
• You need to interact with a page (login, click) — use a browser MCP instead

Setup

1. Get a free API key: https://app.tavily.com (1000 free searches/month)

2. Export it:

   export TAVILY_API_KEY="tvly-YOUR_KEY_HERE"
   

   Add to ~/.zshrc or ~/.bashrc for persistence. Never commit the key.

3. First run will auto-install dependencies via uv:

   command -v uv || curl -LsSf https://astral.sh/uv/install.sh | sh
   

Search

# Basic search — 5 results, summarised answer
uv run ~/.claude/skills/lich-skills/skills/tavily-search/scripts/search.py "your query"

# More results
uv run .../search.py "your query" --max-results 10

# Include full article bodies (slower, more tokens)
uv run .../search.py "your query" --raw-content

# Deeper search with higher recall
uv run .../search.py "your query" --depth advanced

# News-only, last 7 days
uv run .../search.py "your query" --topic news --days 7

# Output as JSON
uv run .../search.py "your query" --json

Flags

Flag	Default	Purpose
--max-results N	5	Number of results to return (1–20)
--depth {basic,advanced}	basic	advanced = slower, higher quality
--topic {general,news}	general	News mode adds recency filtering
--days N	—	With --topic news, restrict to last N days
--raw-content	off	Include full article body as markdown
--include-domains a,b	—	Restrict to comma-separated domains
--exclude-domains a,b	—	Exclude comma-separated domains
--json	off	Machine-readable JSON output

Extract a single URL

uv run .../search.py --extract https://example.com/article

Returns clean markdown of the page body (no nav, ads, or boilerplate).

Output format (default, human-readable)

ANSWER: <Tavily's synthesised answer, 1–3 sentences>

RESULTS:
[1] <title>
    <url>
    <snippet — 1–2 sentences>

[2] ...

With --raw-content each result gets an indented markdown body below the snippet.

Examples

Research a library:

uv run .../search.py "Gemini 3 Flash Image API pricing" --depth advanced

Get the full article body of a blog post:

uv run .../search.py --extract https://blog.example.com/post --json > post.json

News sweep:

uv run .../search.py "OpenAI Codex release" --topic news --days 3 --max-results 10

Environment

• Key lookup order: --api-key flag → $TAVILY_API_KEY → $TAVILY_KEY
• Default model: Tavily's search and extract endpoints (v1)
• Default timeout: 30s per request

Common failures

Error	Fix
Error: No TAVILY_API_KEY	Export the key or pass --api-key
401 Unauthorized	Key is wrong, revoked, or over quota
429 Rate limit	Wait or upgrade plan
No results	Broaden query, try --depth advanced, drop domain filters

Red flags

• Hardcoding the API key anywhere in this repo
• Passing the key on the command line in shared terminals (shell history leak)
• Using --raw-content with --max-results 20 on every query (burns tokens)

Verification

• $TAVILY_API_KEY is set in env, not in files
• uv run .../search.py "hello world" returns results
• gitleaks detect --source . clean