Tavily Metered Search#

Web search with built-in usage tracking and quota management for Tavily API (free tier: 1000 searches/month).

Quick Start#

bash

# Basic search (Markdown output, default)
python3 {baseDir}/scripts/tavily_search.py --query "AI news today"

# With short answer
python3 {baseDir}/scripts/tavily_search.py --query "what is RAG" --include-answer

# JSON output
python3 {baseDir}/scripts/tavily_search.py --query "python tutorial" --format raw
python3 {baseDir}/scripts/tavily_search.py --query "python tutorial" --format brave

# Skip counting (for testing)
python3 {baseDir}/scripts/tavily_search.py --query "test" --no-count

Arguments#

ArgumentDefaultDescription--query(required)Search query string--max-results5Number of results (1-10), configurable via config file--format``mdOutput: raw (JSON), brave (JSON), md (Markdown)--include-answerfalseInclude AI-generated short answer--search-depth``basic``basic or advanced, configurable via config file--no-countfalseSkip usage tracking (still consumes API quota)

Configuration#

Edit config/config.json to customize default settings:

json

{
  "limit": 900,
  "warningThreshold": 800,
  "searchDepth": "basic",
  "defaultMaxResults": 5
}

SettingDescriptionDefaultlimitMonthly limit, blocks search when reached900warningThresholdWarning threshold, shows alert when reached800searchDepthDefault search depthbasicdefaultMaxResultsDefault number of results5

Usage Tracking#

• Automatic tracking: Each successful search increments a counter stored in data/tavily-usage.json
• Monthly reset: Counter resets on the 1st of each month
• Limit enforcement: When limit is reached, search is blocked with a message suggesting web_fetch as alternative
• Warning alert: When warningThreshold is reached, a reminder is appended to search results

Output Formats#

md (default)#

Human-readable Markdown list:

text

1. Title
   https://example.com
   - Snippet text...

raw#

Full JSON with query, answer?, results: [{title, url, content}]

brave#

Brave-like format: {query, results: [{title, url, snippet}], answer?}

Requirements#

• Tavily API key via either:
  • Environment variable: TAVILY_API_KEY
  • ~/.openclaw/.env file: TAVILY_API_KEY=tvly-...

Get a free API key at https://tavily.com

File Structure#

text

tavily-metered-search/
├── SKILL.md                    # Skill documentation
├── scripts/
│   └── tavily_search.py        # Main search script
├── config/
│   └── config.json             # User configuration
└── data/
    └── tavily-usage.json       # Runtime state (auto-maintained)

Notes#

• Free tier: 1000 searches/month (default limit is 900 to leave buffer)
• Keep --max-results small (3-5) to reduce token usage
• Use --no-count for testing without affecting quota