Perplexity API

The perplexity_search tool gives the agent live web search with citations. It uses Perplexity Sonar via API key.

Step 1 — Get the API key

Visit perplexity.ai/settings/api
Sign in (Google / email)
Add a payment method (Sonar is metered — see pricing on the same page)
Click Generate to create a key starting with pplx-
Copy it

Step 2 — Configure InsightWorker

~/.insightworker/.env:

PERPLEXITY_API_KEY=pplx-<your-key>
PERPLEXITY_MODEL=sonar-pro

Model options:

sonar-pro — recommended; best balance of quality + cost for agentic use
sonar — cheaper, good for simple queries
sonar-reasoning — reasoning-focused, slower

Restart the agent.

Step 3 — Verify

In the chat:

Use perplexity_search to find any material news on Apple Inc in the past 24 hours.

Should return a synthesized answer with source URLs. If it returns "PERPLEXITY_API_KEY is not configured", the env var didn't make it through — check ~/.insightworker/.env and restart the agent.

What the tool sends to Perplexity

The query text you pass in (or that the agent constructs from context)
Optional recency filter (hour / day / week / month / year)
Optional domain_filter (allowlist or -domain to exclude)

The query goes over the public internet to Perplexity's servers. For sensitive prompts where you don't want the query text leaving your tenant, don't use this tool — use web_fetch against your own search index instead.

Cost

Perplexity charges per search + per token. As of writing:

~$5 per 1,000 searches at the request level
Plus per-token output costs

A typical InsightWorker app that watches 10 entities hourly during business hours costs roughly $0.50/day in search fees. Exact numbers move; check perplexity.ai/pricing.

Rotation

Click Generate in the same Perplexity settings UI to create a new key, swap it in .env, restart the agent, then delete the old one. Standard zero-downtime pattern.

Common gotchas

Symptom	Cause	Fix
401 Unauthorized	Key invalid or revoked	Generate a new one
402 Payment Required	No payment method on file	Add one in Perplexity settings
429 rate-limited	Too many requests	Slow down your scheduled queries; the agent's loop detector will trip after 3 retries
Empty results	Recency filter too tight	Drop `recency=hour` to `recency=day`; very recent news may not be indexed yet