RealtimeSearch
One API. Every search engine. Zero downtime.
Stop writing glue code for Serper, Brave, and Bing.
Add your API keys, hit one endpoint, and let failover happen automatically.
Get Started |
How It Works |
Extend |
中文文档
Search backbone of SquadyAI RealtimeAPI — the open-source voice AI platform with sub-450ms latency.
The Problem
You're building an AI agent. It needs web search. Here's what happens next:
Monday: "Serper works great!" → ship it
Tuesday: Serper rate-limited → add Brave as fallback → rewrite half the code
Wednesday: Need Bing too → three API formats, three error handlers, three retry loops
Thursday: Key rotation? Load balancing? Monitoring? → spaghetti
Friday: Production goes down at 3am because one provider changed their API → pain
RealtimeSearch exists so you never have this week.
|
Without RealtimeSearch |
With RealtimeSearch |
| Provider goes down |
Your app breaks |
Auto-failover in ~0ms |
| Rate limited |
429 errors, lost requests |
Routes to engine with available quota |
| Multiple API keys |
Manual rotation logic |
Built-in key pool with round-robin |
| Switch providers |
Rewrite integration code |
Change one env var, zero code change |
| Visibility |
Scattered across dashboards |
Single Prometheus endpoint + web UI |
Get Started in 60 Seconds
git clone https://github.com/SquadyAI/RealtimeSearch.git && cd RealtimeSearch
cp .env.example .env # add at least one API key
docker compose up -d # PostgreSQL included
Open http://localhost:5173 → create your admin account → search.
Get Your API Keys (free)
You need at least one. Add all three for ~5,500 free queries/month with automatic failover:
API Example
curl -X POST http://localhost:8787/v1/search \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"query": "latest AI research", "limit": 10}'
{
"results": [
{ "title": "...", "url": "...", "snippet": "..." }
],
"engine": "serper",
"elapsed": 423
}
Same response schema no matter which engine served it. Your code never changes.
How It Works
Your app
│
▼
┌─────────────────┐
│ RealtimeSearch │
│ :8787 │
└────────┬────────┘
│
┌────────▼────────┐
│ Token Leaky │
│ Bucket (TLB) │
│ │
│ Serper ●●●○○ │ ← 3/5 tokens, good to go
│ Brave ●●●●○ │ ← 4/5 tokens, preferred
│ Bing ○○○○○ │ ← 0/5 tokens, skip
└────────┬────────┘
│
┌──────────┼──────────┐
▼ ▼ ▼
Serper Brave Bing
│
on failure?
retry next ↻
TLB (Token Leaky Bucket) tracks available capacity per engine in real time. Each request is routed to the engine with the most headroom. If it fails, the next engine picks up instantly — your client sees one fast response, not a retry storm.
Features
|
Search Gateway
- Serper (Google), Brave, Bing — out of the box
- Unified response format across all engines
- Pluggable: drop a
.ts file to add any provider
|
Reliability
- TLB: token-based rate limiting with auto-failover
- Round-robin load balancing with key rotation
- Hot-swap engines at runtime — zero restart
|
|
Observability
- Prometheus metrics endpoint
- Optional ClickHouse analytics
- Web dashboard for engine monitoring
|
Security
- JWT + API token auth with RBAC
- First-run setup wizard (no hardcoded creds)
- Per-user API key management
|
Add Your Own Engine
Drop a file in engines/search/. That's it.
// engines/search/myengine.ts
export const engine: Engine = {
name: 'myengine',
async search({ query, apiKey, limit }) {
const res = await fetch('https://api.example.com/search', {
headers: { 'Authorization': `Bearer ${apiKey}` },
body: JSON.stringify({ query, limit }),
method: 'POST',
});
const data = await res.json();
return {
engine: 'myengine',
results: data.items.map(r => ({ title: r.title, url: r.link, snippet: r.desc })),
};
},
};
Add MYENGINE_API_KEYS=... to .env, add myengine to SEARCH_ENGINES — hot-reload picks it up automatically.
The SquadyAI Ecosystem
RealtimeSearch is the search backbone of the SquadyAI RealtimeAPI voice AI platform:
| Project |
What it does |
Link |
| RealtimeAPI |
Core voice AI engine — ASR→LLM→TTS pipeline orchestration in Rust, <450 ms E2E |
SquadyAI/RealtimeAPI |
| RealtimeIntent |
Intent classification — vector search + neural reranking, <100 ms |
SquadyAI/RealtimeIntent |
| RealtimeSearch |
Multi-engine search gateway with automatic failover |
you are here |
┌─────────────────────────────────── RealtimeAPI ───────────────────────────────────┐
│ │
│ Audio ──▶ VAD ──▶ ASR ──▶ RealtimeIntent ──▶ LLM ──▶ TTS ──▶ Audio │
│ │ │
│ ┌──────▼──────────────┐ │
│ │ ★ RealtimeSearch │ │
│ │ web search tool │ │
│ └─────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────────────┘
RealtimeSearch works great standalone, but if you're building voice agents, conversational AI, or anything that needs real-time web grounding — check out RealtimeAPI.
Manual Setup (without Docker)
# Prerequisites: Node.js 22+, Yarn, PostgreSQL
yarn install
cp .env.example .env
# Edit .env: add API keys + set DATABASE_URL
yarn prisma:generate
yarn build && yarn dev
Configuration Reference
| Variable |
Default |
Description |
PORT |
8787 |
Backend server port |
DATABASE_URL |
— |
PostgreSQL connection string (auto-set in Docker) |
SEARCH_ENGINES |
serper,brave,bing |
Enabled search engines (comma-separated) |
{ENGINE}_API_KEYS |
— |
API keys (comma-separated for key pools) |
AUTH_JWT_SECRET |
— |
JWT signing secret (change in production) |
TLB_ENABLED |
true |
Enable Token Leaky Bucket |
TLB_DEFAULT_RPS |
20 |
Requests-per-second limit per engine |
TLB_MAX_RETRIES |
3 |
Max failover attempts across engines |
REDIS_URL |
— |
Optional: Redis for result caching |
CLICKHOUSE_URL |
— |
Optional: ClickHouse for analytics |
See .env.example for the full list.
API Reference
All endpoints require auth (JWT or API token) unless noted.
# Search
POST /v1/search { "query": "...", "limit": 10, "locale": "en-US" }
# Auth
POST /v1/auth/register { "username": "...", "password": "..." }
POST /v1/auth/login { "username": "...", "password": "..." }
# Monitoring (public)
GET /healthz
GET /metrics
# Engine management
GET /v1/engines/list
GET /v1/tlb/status
See API_TOKEN_README.md for programmatic token management.
Project Structure
RealtimeSearch/
├── apps/
│ ├── backend/ # Fastify API server
│ │ ├── engines/
│ │ │ └── search/ # Engine plugins (serper, brave, bing, ...)
│ │ ├── src/
│ │ │ ├── server.ts # Server setup, auth, engine loading
│ │ │ ├── engines/ # TLB, routing, failover logic
│ │ │ ├── http/routes/ # API route handlers
│ │ │ └── metrics/ # Prometheus metrics
│ │ └── prisma/ # Database schema & migrations
│ └── web/ # React dashboard (Vite)
├── docker-compose.yml # One-command deploy (incl. PostgreSQL)
├── Dockerfile.backend
└── Dockerfile.frontend
Contributing
PRs welcome. If you find a bug or want to add a new engine, open an issue or submit a pull request.
License
Apache License 2.0 — free for commercial use.