Tavily Web

Tavily Web Search & Research

CLI-based web search, extraction, crawling, and research via curl. No SDK installation required.

Prerequisites

• TAVILY_API_KEY set in environment
• Never hardcode or paste API keys into chat

Choosing the Right Method

Quick Reference

search — Web Search

curl -s "https://api.tavily.com/search" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "your search query here",
    "max_results": 5,
    "search_depth": "basic",
    "topic": "general"
  }'

Key parameters:

See references/search.md for full parameter reference and optimization tips.

extract — URL Content Extraction

curl -s "https://api.tavily.com/extract" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/page"],
    "extract_depth": "basic",
    "query": "focus on pricing info",
    "chunks_per_source": 3,
    "format": "markdown"
  }'

Key parameters:

See references/extract.md for full reference.

crawl — Site-Wide Extraction

curl -s "https://api.tavily.com/crawl" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "max_breadth": 10,
    "limit": 20,
    "instructions": "Find API documentation pages",
    "extract_depth": "basic"
  }'

Key parameters:

See references/crawl.md for full reference.

map — URL Discovery

curl -s "https://api.tavily.com/map" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.example.com"
  }'

Returns a list of URLs found on the site. Useful as a precursor to targeted extract calls (Map-then-Extract pattern).

research — AI-Powered Research

# Start research task
curl -s "https://api.tavily.com/research" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Analyze the competitive landscape for X in the SMB market",
    "model": "auto",
    "citation_format": "numbered"
  }'
# Returns: { "request_id": "..." }

# Poll for completion
curl -s "https://api.tavily.com/research/REQUEST_ID" \
  -H "Authorization: Bearer $TAVILY_API_KEY"
# Poll every 10s until status is "completed" or "failed"

Model selection: mini (focused queries, faster), pro (comprehensive, multi-topic), auto (let Tavily decide).

See references/research.md for prompting best practices and structured output schemas.

Procedure

1. Formulate query — Keep under 400 chars. Split multi-part questions into 2-4 focused sub-queries.
2. Pick topic — general for most searches, news for current events (pair with time_range), finance for market data.
3. Pick depth — Start with basic (1 credit). Use advanced (2 credits) only when precision matters.
4. Keep results small — Default max_results to 5. Filter by score and domain trust.
5. Two-step for full text — Run search first, then extract on 1-3 top URLs. This is cheaper and safer than include_raw_content.
6. Cite sources — Always include results[].url as citations in your final answer.
7. For deep research — Use research endpoint with polling. Include citation_format for automatic source attribution.

Pitfalls

Verification

Check remaining credits:

curl -s "https://api.tavily.com/usage" \
  -H "Authorization: Bearer $TAVILY_API_KEY"

Troubleshooting

Keep request_id from responses for debugging.