SuperAPI AI Directory

tavily-search

General & other

View repository

Updated 10-16 09:38

About this skill

Tavily Search Skill

Search the web and get LLM-optimized results. Preferred over web-search when you need structured relevance scoring, domain filtering, or time-range filtering without spinning up a local browser.

Authentication

Set TAVILY_API_KEY in ~/.openclaw/.env.local:

TAVILY_API_KEY=tvly-your-api-key-here

Get a key at https://tavily.com (1,000 free credits/month).

When to Use This Skill

  • Finding current news, events, or information beyond your knowledge cutoff
  • Researching a topic from trusted/specific domains
  • Time-scoped queries (e.g. "past week", "past month")
  • When you need relevance scores to rank and filter results
  • Quick factual lookups where browser automation would be overkill

Prefer tavily-research for deep multi-source synthesis or market analysis.

Quick Start

# Basic search
curl -s -X POST https://api.tavily.com/search \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest Claude model releases 2025", "max_results": 5}'

API Reference

Endpoint: POST https://api.tavily.com/search

Request Fields

Field Type Default Description
query string Required Search query (keep under 400 chars)
max_results integer 10 Max results returned (1–20)
search_depth string "basic" ultra-fast / fast / basic / advanced
topic string "general" Search topic category
time_range string null day / week / month / year
start_date string null Return results after this date (YYYY-MM-DD)
end_date string null Return results before this date (YYYY-MM-DD)
include_domains array [] Restrict to these domains (max 300)
exclude_domains array [] Exclude these domains (max 150)
country string null Boost results from a specific country
include_raw_content boolean false Include full page content in results
include_images boolean false Include image results

Response Format

{
  "query": "latest Claude model releases 2025",
  "results": [
    {
      "title": "Page Title",
      "url": "https://example.com/page",
      "content": "Extracted text snippet...",
      "score": 0.91
    }
  ],
  "response_time": 1.2
}

Search Depth Guide

Depth Latency Use When
ultra-fast Lowest Real-time chat, quick lookups
fast Low Latency matters but need chunks
basic Medium General-purpose (default)
advanced Higher Precision critical, best relevance

Examples

Recent news with time filter

curl -s -X POST https://api.tavily.com/search \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI agent frameworks news",
    "time_range": "week",
    "max_results": 10
  }'

Domain-restricted search

curl -s -X POST https://api.tavily.com/search \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Python async patterns",
    "include_domains": ["docs.python.org", "realpython.com", "github.com"],
    "search_depth": "advanced"
  }'

With full page content

curl -s -X POST https://api.tavily.com/search \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "openclaw agent config format",
    "max_results": 3,
    "include_raw_content": true
  }'

Tips

  • Keep queries under 400 characters — think search terms, not prompts
  • Break complex topics into multiple targeted sub-queries
  • Use include_domains to focus on authoritative sources
  • Use score field (0–1) to filter low-relevance results; discard below 0.5
  • Use time_range when the user asks about recent events or news
  • advanced depth is recommended when result quality matters more than speed