Identify and avoid Perplexity anti-patterns and common integration mistakes.
Use when reviewing Perplexity code, onboarding new developers,
or auditing existing integrations for best practices violations.
Trigger with phrases like "perplexity mistakes", "perplexity anti-patterns",
"perplexity pitfalls", "perplexity code review", "perplexity gotchas".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Identify and avoid Perplexity anti-patterns and common integration mistakes.
Use when reviewing Perplexity code, onboarding new developers,
or auditing existing integrations for best practices violations.
Trigger with phrases like "perplexity mistakes", "perplexity anti-patterns",
"perplexity pitfalls", "perplexity code review", "perplexity gotchas".
allowed-tools
Read, Grep
version
1.12.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","perplexity","audit"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
Perplexity Known Pitfalls
Overview
Real gotchas when integrating Perplexity Sonar API. Perplexity uses an OpenAI-compatible chat endpoint but performs live web searches -- a fundamentally different paradigm from standard LLM completions. These pitfalls come from treating it like a regular chatbot.
Prerequisites
Perplexity API key configured
Understanding of OpenAI-compatible chat API format
Pitfalls
1. Using It as a Generic Chatbot
Perplexity searches the web per request. Using it for tasks that don't need web search wastes money.
# BAD: general chatbot (wastes a search query)
response = call_perplexity("Write me a haiku about cats")
# Costs $0.005+ for something any LLM can do offline# GOOD: leverage web search capability
response = call_perplexity(
"What are the latest Next.js 15 features released this month?",
search_recency_filter="month"
)
2. Ignoring Citations
Perplexity returns [1], [2] markers in text with a separate citations array. Ignoring them loses the key value prop.
data = response.model_dump() # or response.json() for raw HTTP
answer = data["choices"][0]["message"]["content"]
citations = data.get("citations", []) # NOT in choices — top-level field# BAD: displaying raw markersprint(answer) # "According to [1], Node.js 22 adds..."# GOOD: replace markers with linksimport re
for i, url inenumerate(citations, 1):
answer = answer.replace(f"[{i}]", f"{i}")
3. Using Wrong SDK Import
There is no @perplexity/sdk or Python package. Use the standard OpenAI client.
perplexity
// BAD — this package doesn't existimport { PerplexityClient } from"@perplexity/sdk";
// GOOD — use OpenAI client with Perplexity base URLimportOpenAIfrom"openai";
const client = newOpenAI({
apiKey: process.env.PERPLEXITY_API_KEY,
baseURL: "https://api.perplexity.ai",
});
4. Not Setting max_tokens
Without max_tokens, responses can be arbitrarily long, increasing costs unpredictably.
// BAD: no token limit — output cost can spikeawait client.chat.completions.create({
model: "sonar-pro", // $15/M output tokens!messages: [{ role: "user", content: "Tell me about AI" }],
});
// GOOD: always set max_tokensawait client.chat.completions.create({
model: "sonar-pro",
messages: [{ role: "user", content: "Tell me about AI" }],
max_tokens: 1024,
});
5. No Recency Filter for Time-Sensitive Queries
Without search_recency_filter, Perplexity may cite outdated articles.
# BAD: may return articles from any time period
response = call_perplexity("current Bitcoin price")
# GOOD: constrain to recent results
response = call_perplexity(
"current Bitcoin price",
search_recency_filter="day"# hour | day | week | month
)
6. Sending Full Conversation History
Each message in the conversation may trigger new search queries. Sending 20 turns of history is expensive and slow.
# BAD: 20 turns of history = many search queries
messages = long_history + [{"role": "user", "content": "summarize"}]
# GOOD: summarize context, send focused query
messages = [
{"role": "system", "content": "Answer based on web search."},
{"role": "user", "content": f"Context: {summary}\nQuestion: {question}"}
]
7. Using sonar-pro for Simple Queries
sonar-pro costs 3-15x more than sonar. Using it for simple factual lookups wastes budget.
// BAD: sonar-pro for a trivial questionawait client.chat.completions.create({
model: "sonar-pro", // $3 input + $15 output per M tokensmessages: [{ role: "user", content: "What is the capital of France?" }],
});
// GOOD: match model to complexityconst model = isComplexQuery(query) ? "sonar-pro" : "sonar";
8. Mixing Allowlist and Denylist in Domain Filter
search_domain_filter supports either allowlist (include) or denylist (exclude with - prefix), but not both in the same request.
