Run AI web searches using Perplexity Sonar models through LiteLLM and OpenRouter. Perplexity returns real-time, web-grounded answers with source citations — ideal for current information, recent literature, and facts beyond the model's training cutoff. One OpenRouter key covers all models; no separate Perplexity account needed.
When to Use This Skill
Use for: current developments, latest publications, citation-grounded answers, verifying a claim against current sources, or anything past the training cutoff.
Skip for: arithmetic/logic, code execution, or facts well within training data (answer directly).
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
Unsure which search backend fits; want automatic routing and results saved to sources/ |
alterlab-research-lookup |
| General web, market, or technical research via Parallel, or extracting a known URL | alterlab-parallel-web |
| Per-paper structured experimental data (sample sizes, effect sizes, quality scores) | alterlab-bgpt-search |
| Reproducible biomedical database search by MeSH terms or PMIDs | alterlab-pubmed |
Setup (one-time)
# 1. Get a key at https://openrouter.ai/keys and add credits ($5+ recommended)
# 2. Configure (either form works; setup_env.py writes .env with owner-only permissions)
export OPENROUTER_API_KEY='sk-or-v1-your-key-here'
python scripts/setup_env.py --api-key sk-or-v1-your-key-here # writes .env
# 3. Install LiteLLM
uv pip install litellm
# 4. Verify
python scripts/perplexity_search.py --check-setup
--check-setup reads the live environment, not .env. After setup_env.py, load the file with set -a; source .env; set +a (plain source does not export) or use python-dotenv, so the variable is actually in scope. Ask the user to set the key themselves rather than pasting it into the conversation. See references/openrouter_setup.md for full setup, security, and troubleshooting.
Basic usage
python scripts/perplexity_search.py "What are the latest developments in CRISPR gene editing?"
python scripts/perplexity_search.py "Recent CAR-T therapy clinical trials" --output results.json
python scripts/perplexity_search.py "Compare mRNA and viral vector vaccines" --model sonar-pro-search
python scripts/perplexity_search.py "Quantum computing for drug discovery" --verbose
The CLI takes the bare model name (e.g. sonar-pro); the script prepends openrouter/perplexity/ automatically.
Models
Select with --model (or set DEFAULT_MODEL):
| Model | Use it for |
|---|---|
sonar-pro (default) |
General research, balanced cost/quality |
sonar-pro-search |
Most advanced agentic, multi-step search; comprehensive comparisons. Highest cost; OpenRouter-exclusive |
sonar |
Simple fact lookups, cost-sensitive bulk queries |
sonar-reasoning-pro |
Tasks needing explicit step-by-step reasoning |
sonar-reasoning was retired on OpenRouter (not listed as of 2026-09-23) and the CLI no longer accepts it; a stale DEFAULT_MODEL=sonar-reasoning now fails fast with a clear error. See references/model_comparison.md for detailed trade-offs, pricing, context windows, and sonar-deep-research for programmatic use.
Writing good queries
Be specific (domain + time frame + desired output). Examples that work well:
- "Latest clinical trial results for CAR-T therapy in B-cell lymphoma published in 2024"
- "Compare PyTorch vs TensorFlow for transformer training: ease of use, performance, ecosystem — with recent benchmarks"
- "Evidence for intermittent fasting on HbA1c in adults with type 2 diabetes; focus on RCTs"
Add source preferences ("peer-reviewed", "clinicaltrials.gov", "FDA-approved") for higher-quality grounding. Full query-design patterns, domain templates, and pitfalls live in references/search_strategies.md.
Programmatic access
from scripts.perplexity_search import search_with_perplexity
result = search_with_perplexity(
query="What are the latest CRISPR developments?",
model="openrouter/perplexity/sonar-pro", # full path required when calling directly
max_tokens=4000,
temperature=0.2,
)
if result["success"]:
print(result["answer"])
print(f"Tokens: {result['usage']['total_tokens']}")
else:
print(f"Error: {result['error']}")
Saved JSON (--output) carries answer, model, usage, and citations — a deduplicated list of {url, title} gathered from OpenRouter's url_citation annotations and Perplexity's citations/search_results fields, present when the model returns sources. Process with jq '.answer' or jq '.citations[].url'. Cite the underlying sources, not Perplexity, and open any source you quote: answers are generated summaries and can misattribute a claim.
Cost
Pricing is per token (plus a per-request fee on sonar-pro-search); rough per-query order: sonar < sonar-pro < sonar-reasoning-pro < sonar-pro-search. Control spend by matching the model to the query, capping --max-tokens, and setting a spending limit in the OpenRouter dashboard. Monitor usage at https://openrouter.ai/activity. Exact rates: references/model_comparison.md and https://openrouter.ai/perplexity.
Environment variables
OPENROUTER_API_KEY(required)DEFAULT_MODEL(defaultsonar-pro),DEFAULT_MAX_TOKENS(default4000),DEFAULT_TEMPERATURE(default0.2) — honored as CLI defaults; override per call with the matching flag.
Resources
scripts/perplexity_search.py— search CLI / importable functionscripts/setup_env.py— key setup and validationreferences/openrouter_setup.md— setup, security, troubleshootingreferences/model_comparison.md— model selection and pricingreferences/search_strategies.md— query designassets/.env.example— environment template
Part of the AlterLab Academic Skills suite.