Tavily Metered Search

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

Quick Start

# 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

Configuration

Edit config/config.json to customize default settings:

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

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:

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

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