Identify and avoid Exa anti-patterns and common integration mistakes.
Use when reviewing Exa code for issues, onboarding new developers,
or auditing existing Exa integrations for best practices violations.
Trigger with phrases like "exa mistakes", "exa anti-patterns",
"exa pitfalls", "exa what not to do", "exa code review".
Real gotchas when integrating Exa's neural search API. Exa uses embeddings-based search rather than keyword matching, which creates a different class of failure modes than traditional search APIs. This skill covers the top pitfalls with wrong/right examples.
Pitfall 1: Keyword-Style Queries
Exa's neural search interprets natural language semantically. Boolean operators and keyword syntax degrade results.
import Exa from "exa-js";
const exa = new Exa(process.env.EXA_API_KEY);
// BAD: keyword/boolean style — Exa ignores AND/OR
const bad = await exa.search(
"python AND machine learning OR deep learning 2024"
);
// GOOD: natural language statement
const good = await exa.search(
"recent tutorials on building ML models with Python",
{ type: "neural", numResults: 10 }
);
Pitfall 2: Wrong Search Type
Using neural search for exact lookups (URLs, names) or keyword search for conceptual queries silently degrades quality.
// BAD: neural search for a specific URL/identifier
const bad = await exa.search("arxiv.org/abs/2301.00001", { type: "neural" });
// GOOD: keyword for exact terms, neural for concepts
const exactMatch = await exa.search("arxiv.org/abs/2301.00001", {
type: "keyword",
});
const conceptual = await exa.search(
"transformer architecture improvements for long context",
{ type: "neural" }
);
Pitfall 3: Expecting Content from search()
search() returns metadata only (URL, title, score). Content requires searchAndContents() or getContents().
Date filters silently exclude results. A single-day window often returns nothing without error.
// BAD: too narrow, likely returns empty array
const bad = await exa.search("AI news", {
startPublishedDate: "2025-03-15T00:00:00.000Z",
endPublishedDate: "2025-03-15T23:59:59.000Z",
});
// GOOD: reasonable window with fallback
let results = await exa.search("AI news", {
startPublishedDate: "2025-03-01T00:00:00.000Z",
endPublishedDate: "2025-03-31T23:59:59.000Z",
numResults: 10,
});
// Fallback if no results
if (results.results.length === 0) {
results = await exa.search("AI news", { numResults: 10 });
}
Pitfall 5: findSimilar Takes a URL, Not a Query
findSimilar expects a URL as its first argument. Passing a query string gives meaningless results.
// BAD: passing a query string to findSimilar
const bad = await exa.findSimilar("machine learning research papers");
// GOOD: pass a URL — findSimilar finds pages semantically similar to it
const good = await exa.findSimilar("https://arxiv.org/abs/2301.00001", {
numResults: 10,
excludeSourceDomain: true,
});
Pitfall 6: Date Filters with company/people Categories
The company and people categories do NOT support date filters. Using them returns a 400 error.
// BAD: date filter with company category → 400 error
const bad = await exa.search("AI startups", {
category: "company",
startPublishedDate: "2024-01-01T00:00:00.000Z", // not supported!
});
// GOOD: company search without date filters
const good = await exa.search("AI startups", {
category: "company",
numResults: 10,
});
Pitfall 7: Not Limiting Content Size
Requesting full text without maxCharacters can return massive payloads, increasing latency and cost.
// BAD: unlimited text retrieval
const bad = await exa.searchAndContents("topic", {
numResults: 20,
text: true, // could return megabytes of content
});
// GOOD: limit content size
const good = await exa.searchAndContents("topic", {
numResults: 10,
text: { maxCharacters: 2000 }, // cap at 2000 chars per result
highlights: { maxCharacters: 500 },
});
Pitfall 8: Creating New Client Per Request
Each new Exa() call creates a new HTTP client. Reuse a singleton for connection pooling.
// BAD: new client every request (in a route handler)
app.get("/search", async (req, res) => {
const exa = new Exa(process.env.EXA_API_KEY); // wasteful!
const results = await exa.search(req.query.q);
res.json(results);
});
// GOOD: singleton client
const exa = new Exa(process.env.EXA_API_KEY);
app.get("/search", async (req, res) => {
const results = await exa.search(req.query.q);
res.json(results);
});
Pitfall 9: Ignoring the requestId in Errors
Exa error responses include requestId for support debugging. Always log it.
