Brave Rotator

Multi-key Brave Search with automatic round-robin rotation and rate-limit fallback.

Setup

Set env var with comma-separated keys:

export BRAVE_API_KEYS=key1,key2,key3

Optionally set state file path (default: ~/.brave_key_state.json):

export BRAVE_KEY_STATE_FILE=/path/to/state.json

Script: scripts/brave_search.py

Run directly or import as module.

CLI usage

python3 brave_search.py "your query" [--count 5] [--type web|news|image] [--country us] [--lang en] [--json]

Import usage

import sys, os
sys.path.insert(0, "path/to/skill/scripts")
from brave_search import search, format_results

data, used_key, key_idx = search("your query", count=5, search_type="web")
results = format_results(data, "web")
# results = [{"title": ..., "url": ..., "snippet": ...}, ...]

Rotation Logic

• Maintains state in ~/.brave_key_state.json
• Round-robin across all keys
• On HTTP 429/403: blocks key for 60s, retries with next key
• All keys exhausted: uses least recently blocked key

Key State Inspection

cat ~/.brave_key_state.json

Shows per-key request count, last success, and blocked_until timestamps.

Search Types

| Type | Endpoint | Result fields | |-------|-----------------------|--------------------------------------| | web | /web/search | title, url, snippet | | news | /news/search | title, url, snippet, age | | image | /images/search | title, url, thumbnail |

Notes

• Free plan: 2000 req/month/key, 1 req/sec
• With N keys: effectively N×2000 req/month
• See references/brave-api.md for full API params and plan details