Exa Hello World

Overview

Minimal working examples demonstrating all core Exa search operations: basic search, search with contents, find similar, and get contents. Each example is runnable standalone.

Prerequisites

• exa-js SDK installed (npm install exa-js)
• EXA_API_KEY environment variable set
• Node.js 18+ with ES module support

Instructions

Step 1: Basic Search (Metadata Only)

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

// Basic search returns URLs, titles, and scores — no page content
const results = await exa.search("best practices for building RAG pipelines", {
  type: "auto",       // auto | neural | keyword | fast | instant
  numResults: 5,
});

for (const r of results.results) {
  console.log(`[${r.score.toFixed(2)}] ${r.title}`);
  console.log(`  ${r.url}`);
}

Step 2: Search with Contents

// searchAndContents returns text, highlights, and/or summary with each result
const results = await exa.searchAndContents(
  "how transformers work in large language models",
  {
    type: "neural",
    numResults: 3,
    text: { maxCharacters: 1000 },
    highlights: { maxCharacters: 500, query: "attention mechanism" },
    summary: { query: "explain transformers simply" },
  }
);

for (const r of results.results) {
  console.log(`## ${r.title}`);
  console.log(`URL: ${r.url}`);
  console.log(`Summary: ${r.summary}`);
  console.log(`Text preview: ${r.text?.substring(0, 200)}...`);
  console.log(`Highlights: ${r.highlights?.join(" | ")}`);
  console.log();
}

Step 3: Find Similar Pages

// findSimilar takes a URL and returns semantically similar pages
const similar = await exa.findSimilarAndContents(
  "https://arxiv.org/abs/2301.00234",
  {
    numResults: 5,
    text: { maxCharacters: 500 },
    excludeSourceDomain: true,
  }
);

console.log("Pages similar to the seed URL:");
for (const r of similar.results) {
  console.log(`  ${r.title} — ${r.url}`);
}

Step 4: Get Contents for Known URLs

// getContents retrieves page content for specific URLs
const contents = await exa.getContents(
  ["https://example.com/article-1", "https://example.com/article-2"],
  {
    text: { maxCharacters: 2000 },
    highlights: { maxCharacters: 500 },
    livecrawl: "preferred",
    livecrawlTimeout: 10000,
  }
);

for (const r of contents.results) {
  console.log(`${r.title}: ${r.text?.length} chars retrieved`);
}

Output

• Working TypeScript file with Exa client initialization
• Search results printed to console with titles, URLs, and scores
• C

Exa Install & Auth

Overview

Install the official Exa SDK and configure API key authentication. Exa is a neural search API at api.exa.ai that retrieves web content using semantic similarity. Authentication uses the x-api-key header. The SDK is exa-js on npm or exa-py on PyPI.

Prerequisites

• Node.js 18+ or Python 3.10+
• Package manager (npm, pnpm, yarn, or pip)
• Exa account at dashboard.exa.ai
• API key from the Exa dashboard

Instructions

Step 1: Install the SDK

Node.js (exa-js)

set -euo pipefail
npm install exa-js
# or
pnpm add exa-js

Python (exa-py)

pip install exa-py

Step 2: Configure the API Key

# Set environment variable
export EXA_API_KEY="your-api-key-here"

# Or create .env file (add .env to .gitignore first)
echo 'EXA_API_KEY=your-api-key-here' >> .env

Add to .gitignore:

.env
.env.local
.env.*.local

Step 3: Initialize the Client

TypeScript

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

Python

from exa_py import Exa
import os

exa = Exa(api_key=os.environ["EXA_API_KEY"])

Step 4: Verify Connection

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

async function verifyConnection() {
  try {
    const result = await exa.search("test connectivity", { numResults: 1 });
    console.log("Connected. Results:", result.results.length);
    console.log("First result:", result.results[0]?.title);
  } catch (err: any) {
    if (err.status === 401) {
      console.error("Invalid API key. Check EXA_API_KEY.");
    } else if (err.status === 402) {
      console.error("No credits remaining. Top up at dashboard.exa.ai.");
    } else {
      console.error("Connection failed:", err.message);
    }
  }
}

verifyConnection();

Output

• exa-js or exa-py installed in project dependencies
• EXA_API_KEY environment variable configured
• .env added to .gitignore
• Successful search result confirming connectivity

Error Handling

Examples

For a compliance research task, constrain Exa to approved primary domains and date range, inspect each result/citation, and retain only the summarized, non-sensitive evidence. Reject results that lack support rather than widening the query into private data.

Overview

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 a

Exa Load & Scale

Output

• A measured, rate-aware search/research workload with bounded concurrency, idempotent work tracking, owner, and rollback threshold.
• An aggregate capacity receipt that excludes raw queries, customer data, API keys, and full result content.

Examples

Use sanitized test queries to increase concurrency gradually below the approved limit, record aggregate latency, 429s, completion, and queue age, and apply backoff with jitter. Reduce load on throttling or quality regression; do not replay customer queries or bypass policy/rate controls to reach a benchmark.

Overview

Load testing and capacity planning for Exa integrations. Key constraint: Exa's default rate limit is 10 QPS. Scaling strategies focus on caching, request queuing, parallel processing within rate limits, and search type selection for latency budgets.

Prerequisites

• k6 load testing tool installed
• Test environment Exa API key (separate from production)
• Redis for result caching

Capacity Reference

With caching (50% hit rate): Effective throughput doubles to 20 req/s equivalent.

Instructions

Step 1: k6 Load Test Against Your Wrapper

// exa-load-test.js
import http from "k6/http";
import { check, sleep } from "k6";

export const options = {
  stages: [
    { duration: "1m", target: 5 },    // Ramp up to 5 VUs
    { duration: "3m", target: 5 },    // Steady state
    { duration: "1m", target: 10 },   // Push toward rate limit
    { duration: "2m", target: 10 },   // Stress test
    { duration: "1m", target: 0 },    // Ramp down
  ],
  thresholds: {
    http_req_duration: ["p(95)<3000"],  // 3s P95 for neural search
    http_req_failed: ["rate<0.05"],     // < 5% error rate
  },
};

const queries = [
  "best practices for building RAG systems",
  "transformer architecture improvements 2025",
  "TypeScript 5.5 new features",
  "vector database comparison guide",
  "AI safety alignment research",
];

export default function () {
  const query = queries[Math.floor(Math.random() * queries.length)];

  const response = http.post(
    `${__ENV.APP_URL}/api/search`,
  

Exa Local Dev Loop

Output

• A small reviewed local Exa integration change with focused tests and normal source-control rollback.
• A redacted development verification receipt using sanitized queries and scoped credentials.

Overview

Set up a fast, reproducible local development workflow for Exa integrations. Covers project structure, mock responses for unit tests, integration test patterns, and hot-reload configuration.

Prerequisites

• exa-js installed and EXA_API_KEY configured
• Node.js 18+ with npm/pnpm
• vitest for testing (or jest)

Instructions

Step 1: Project Structure

my-exa-project/
├── src/
│   ├── exa/
│   │   ├── client.ts       # Singleton Exa client
│   │   ├── search.ts       # Search wrappers
│   │   └── types.ts        # Typed interfaces
│   └── index.ts
├── tests/
│   ├── exa.unit.test.ts    # Mock-based unit tests
│   └── exa.integration.test.ts  # Real API tests (needs key)
├── .env.local              # Local secrets (git-ignored)
├── .env.example            # Template for team
├── tsconfig.json
├── vitest.config.ts
└── package.json

Step 2: Package Setup

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:unit": "vitest --testPathPattern=unit",
    "test:integration": "vitest --testPathPattern=integration",
    "build": "tsc"
  },
  "dependencies": {
    "exa-js": "^1.0.0"
  },
  "devDependencies": {
    "tsx": "^4.0.0",
    "vitest": "^2.0.0",
    "typescript": "^5.0.0"
  }
}

Step 3: Mock Exa for Unit Tests

// tests/exa.unit.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";

// Mock the exa-js module
vi.mock("exa-js", () => {
  return {
    default: vi.fn().mockImplementation(() => ({
      search: vi.fn().mockResolvedValue({
        results: [
          { url: "https://example.com/1", title: "Test Result 1", score: 0.95 },
          { url: "https://example.com/2", title: "Test Result 2", score: 0.87 },
        ],
      }),
      searchAndContents: vi.fn().mockResolvedValue({
        results: [
          {
            url: "https://example.com/1",
            title: "Test Result 1",
            score: 0.95,
            text: "This is the full text content of the page.",
            highlights: ["Key excerpt from the page"],
            summary: "A summary of the page content.",
          },
        ],
      }),
      findSimilar: vi.fn().mockResolvedValue({
        re

Exa Migration Deep Dive

Prerequisites

• An inventory of existing retrieval/data flows, policy classification, sanitized evaluation set, acceptance threshold, and rollback owner.
• Separate staging credentials and review for any automation or customer-query migration.

Output

• A staged migration record with compatibility/evaluation evidence, owner, observation window, and rollback configuration.

Examples

Run prior and target retrieval flows against sanitized evaluation queries in staging, compare aggregate citation/quality/latency/error data, then promote an approved canary. Roll back on policy or quality regression; do not bulk-replay customer queries or turn migration output into unreviewed decisions.

Current State

!npm list exa-js 2>/dev/null | grep exa-js || echo 'exa-js not installed' !npm list 2>/dev/null | grep -E '(google|bing|tavily|serper|serpapi)' || echo 'No competing search SDK found'

Overview

Migrate from traditional search APIs (Google Custom Search, Bing Web Search, Tavily, Serper) to Exa's neural search API. Key differences: Exa uses semantic/neural search instead of keyword matching, returns content (text/highlights/summary) in a single API call, and supports similarity search from a seed URL.

API Comparison

Instructions

Step 1: Install Exa SDK

set -euo pipefail
npm install exa-js
# Remove old SDK if replacing
# npm uninstall google-search-api tavily serpapi

Step 2: Create Adapter Layer

// src/search/adapter.ts
import Exa from "exa-js";

// Define a provider-agnostic search interface
interface SearchResult {
  title: string;
  url: string;
  snippet: string;
  score?: number;
  publishedDate?: string;
}

interface SearchResponse {
  results: SearchResult[];
  query: string;
}

// Exa implementation
cl

Exa Multi-Environment Setup

Output

• Isolated development, staging, and production configurations with separate scoped credentials, policy/routing controls, and owners.
• A synthetic-validation promotion receipt with a safe rollback path that avoids production-query experiments.

Examples

Validate a versioned configuration with sanitized queries in development, promote to staging using a separate key, and record quality/latency/policy results. Release through an approved production canary only; restore the prior configuration on regression and never copy production keys or private query data to lower environments.

Overview

Exa charges per search request at api.exa.ai. Multi-environment setup focuses on API key isolation per environment, request limits and caching to control costs in staging, and appropriate numResults/content settings per tier.

Prerequisites

• Exa API key(s) from dashboard.exa.ai
• exa-js installed (npm install exa-js)
• Optional: Redis for search result caching in staging/production

Environment Strategy

Instructions

Step 1: Environment-Aware Configuration

// config/exa.ts
import Exa from "exa-js";

type Env = "development" | "staging" | "production";

interface ExaEnvConfig {
  apiKey: string;
  defaultNumResults: number;
  maxCharacters: number;
  searchType: "auto" | "neural" | "keyword";
  cacheEnabled: boolean;
  cacheTtlSeconds: number;
}

const configs: Record<Env, Omit<ExaEnvConfig, "apiKey"> & { keyVar: string }> = {
  development: {
    keyVar: "EXA_API_KEY",
    defaultNumResults: 3,
    maxCharacters: 500,
    searchType: "auto",
    cacheEnabled: false,
    cacheTtlSeconds: 0,
  },
  staging: {
    keyVar: "EXA_API_KEY_STAGING",
    defaultNumResults: 5,
    maxCharacters: 1000,
    searchType: "auto",
    cacheEnabled: true,
    cacheTtlSeconds: 300,  // 5 minutes
  },
  production: {
    keyVar: "EXA_API_KEY_PROD",
    defaultNumResults: 10,
    maxCharacters: 2000,
    searchType: "neural",
    cacheEnabled: true,
    cacheTtlSeconds: 3600,  // 1 hour
  },
};

export function getExaConfig(): ExaEnvConfig {
  const env = (process.env.NODE_ENV || "development") as Env;

Exa Observability

Output

• Bounded redacted metrics/traces for request outcome, latency, rate headroom, policy decision, source/citation coverage, and fallback behavior.
• An owned alert/runbook path that excludes raw queries, result content, identifiers, and credentials.

Examples

Emit aggregate metrics by environment, endpoint, status class, and policy outcome, then trigger a sanitized staging failure to verify alert routing. Record correlation ID and remediation time only; do not put customer queries, result text, or API keys into logs, dashboards, or tickets.

Overview

Monitor Exa search API performance, result quality, and cost efficiency. Key metrics: search latency by type (neural ~500-2000ms, keyword ~200-500ms), result count per query, cache hit rates, error rates by status code, and daily search volume for budget tracking.

Prerequisites

• Exa API integration in production
• Metrics backend (Prometheus, Datadog, or OpenTelemetry)
• Alerting system (PagerDuty, Slack, or equivalent)

Instructions

Step 1: Instrument the Exa Client

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

// Generic metrics emitter (replace with your metrics library)
function emitMetric(name: string, value: number, tags: Record<string, string>) {
  // Prometheus: histogram/counter.observe(value, tags)
  // Datadog: dogstatsd.histogram(name, value, tags)
  // OpenTelemetry: meter.createHistogram(name).record(value, tags)
  console.log(`[metric] ${name}=${value}`, tags);
}

async function trackedSearch(query: string, options: any = {}) {
  const start = performance.now();
  const type = options.type || "auto";
  const hasContents = options.text || options.highlights || options.summary;

  try {
    const method = hasContents ? "searchAndContents" : "search";
    const results = hasContents
      ? await exa.searchAndContents(query, options)
      : await exa.search(query, options);

    const duration = performance.now() - start;

    emitMetric("exa.search.duration_ms", duration, { type, method });
    emitMetric("exa.search.result_count", results.results.length, { type });
    emitMetric("exa.search.success", 1, { type });

    return results;
  } catch (err: any) {
    const duration = performance.now() - start;
    const status = String(err.status || "unknown");

    emitMetric("exa.search.duration_ms", duration, { type, status });
    emitMetric("exa.search.error", 1, { type, status });

    throw err;
  }
}

Step 2: Track Result Quality

// Measure whether search results are actually used downstream
function trackResultUsage(
  searchId: string,
  resultIndex: number,
  action: "clicked" | "used_in_con

Exa Performance Tuning

Prerequisites

• A measured latency/throughput/quality/error baseline, sanitized evaluation set, SLO owner, and rollback threshold.
• Approved data/policy controls that remain in effect during tests.

Output

• A measured performance recommendation with policy/quality guardrails, owner, and reversible change record.

Examples

Measure sanitized staging queries, change one request option, cache behavior, or concurrency limit, and compare aggregate latency, quality, and errors against baseline. Revert on regression; do not disable citation, source, privacy, or human-review controls to improve a metric.

Overview

Optimize Exa search API response times for production workloads. Key levers: search type selection (instant < fast < auto < neural < deep), result count reduction, content scope control, result caching, and parallel query execution.

Latency by Search Type

Instructions

Step 1: Match Search Type to Latency Budget

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

function selectSearchType(latencyBudgetMs: number) {
  if (latencyBudgetMs < 200) return "instant";
  if (latencyBudgetMs < 500) return "fast";
  if (latencyBudgetMs < 1500) return "auto";
  if (latencyBudgetMs < 3000) return "neural";
  return "deep";
}

async function optimizedSearch(query: string, latencyBudgetMs: number) {
  const type = selectSearchType(latencyBudgetMs);
  const numResults = latencyBudgetMs < 500 ? 3 : latencyBudgetMs < 2000 ? 5 : 10;

  return exa.search(query, { type, numResults });
}

Step 2: Minimize Content Retrieval

// Each content option adds latency. Only request what you need.

// Fastest: metadata only (no content retrieval)
const metadataOnly = await exa.search("query", { numResults: 5 });

// Medium: highlights only (much smaller than full text)
const highlightsOnly = await exa.searchAndContents("query", {
  numResults: 5,
  highlights: { maxCharacters: 300 },
  // No text or summary — saves conte

Exa Policy Guardrails

Output

• A versioned policy-control configuration with owner, scope, enforcement/evaluation evidence, exception path, and rollback decision.

Examples

Test a guardrail using a sanitized query that should be allowed and one that should be blocked, verify the redacted decision/audit record, and review any exception through the designated owner. Do not encode private data or weaken guardrails solely to obtain a desired retrieval result.

Overview

Policy enforcement for Exa neural search integrations. Exa searches the open web, so results may include unreliable sources, competitor content, or inappropriate material. This skill covers domain allowlists/blocklists (via Exa's includeDomains/excludeDomains), content moderation, query sanitization, freshness policies, and per-user budget enforcement.

Prerequisites

• exa-js installed and configured
• Content policy requirements defined
• Redis for per-user quota tracking (optional)

Instructions

Step 1: Domain Filtering (Built-in Exa Feature)

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

// Exa supports up to 1200 domains in includeDomains/excludeDomains
const TRUSTED_SOURCES = {
  medical: [
    "pubmed.ncbi.nlm.nih.gov", "who.int", "cdc.gov",
    "nejm.org", "nature.com", "thelancet.com",
  ],
  technical: [
    "github.com", "stackoverflow.com", "developer.mozilla.org",
    "docs.python.org", "nodejs.org", "arxiv.org",
  ],
  news: [
    "reuters.com", "apnews.com", "bbc.com",
    "techcrunch.com", "arstechnica.com",
  ],
};

const BLOCKED_DOMAINS = [
  "competitor1.com", "competitor2.io",
  "spam-farm.com", "content-mill.net",
];

async function policySearch(
  query: string,
  category: keyof typeof TRUSTED_SOURCES | "general"
) {
  const opts: any = {
    type: "auto",
    numResults: 10,
    text: { maxCharacters: 1000 },
    moderation: true,  // Exa's built-in content moderation
  };

  if (category !== "general" && TRUSTED_SOURCES[category]) {
    opts.includeDomains = TRUSTED_SOURCES[category];
  } else {
    opts.excludeDomains = BLOCKED_DOMAINS;
  }

  return exa.searchAndContents(query, opts);
}

Step 2: Query Content Policy

const BLOCKED_PATTERNS = [
  /how to (hack|exploit|attack|ddos)/i,
  /(buy|purchase|order)\s+(drugs|weapons|firearms)/i,
  /personal.*(address|phone|ssn|social security)/i,
  /generate.*(malware|ransomware|virus)/i,
];

function validateQuery(input: string): string {
  for (const pattern of BLOCKED_PATTERNS) {
 

Exa Production Checklist

Prerequisites

• A named service/policy/data owner, approved model/provider route, production rollback plan, and passing staging evidence.

Instructions

1. Complete evidence gates for identity/secrets, data handling, policy controls, source/citation requirements, observability, rate limits, and rollback.
2. Validate an approved non-sensitive canary and verify its expected routing/guardrail behavior.
3. Block release when any security, policy, data, ownership, or recovery gate is unverified.

Output

• A production-readiness receipt with evidence, owners, exceptions, canary result, and rollback path.

Examples

Release an approved staging configuration to a small canary using sanitized queries, verify policy/source/citation and alert behavior, then observe the defined window. Restore the previous configuration if any guardrail or SLO fails; do not widen automation to conceal a failure.

Overview

Complete checklist for deploying Exa search integrations to production. Covers API key management, error handling verification, performance baselines, monitoring, and rollback procedures.

Pre-Deployment Checklist

Security

• [ ] Production API key stored in secret manager (not env file)
• [ ] Different API keys for dev/staging/production
• [ ] .env files in .gitignore
• [ ] Git history scanned for accidentally committed keys
• [ ] API key has minimal scopes needed

Code Quality

• [ ] All tests passing (unit + integration)
• [ ] No hardcoded API keys or URLs
• [ ] Error handling covers all Exa HTTP codes (400, 401, 402, 403, 429, 5xx)
• [ ] requestId captured from error responses
• [ ] Rate limiting/exponential backoff implemented
• [ ] Content moderation enabled (moderation: true) for user-facing search

Performance

• [ ] Search type appropriate for latency SLO (fast/auto/neural)
• [ ] numResults minimized per use case (3-5 for most)
• [ ] maxCharacters set on text and highlights
• [ ] Result caching enabled (LRU or Redis)
• [ ] Request queue with concurrency limit (respect 10 QPS default)

Monitoring

• [ ] Search latency histogram instrumented
• [ ] Error rate counter by status code
• [ ] Cache hit/miss rate tracked
• [ ] Daily search volume tracked (for budget)
• [ ] Alerts configured for latency > 3s, error rate > 5%

Deploy Procedure

Step 1: Pre-Flight Verification

set -euo pipefail
echo "=== Exa Pre-Flight ==="

# 1. Verify production API key works
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_cod

Exa Rate Limits

Output

• A rate-aware client/workflow with bounded concurrency, idempotency, backoff, monitoring, and safe recovery decisions.
• An aggregate throttle receipt that excludes raw queries, result content, and credentials.

Overview

Handle Exa API rate limits gracefully. Default limit is 10 QPS (queries per second) across all endpoints. Rate limit errors return HTTP 429 with a simple { "error": "rate limit exceeded" } response. For higher limits, contact hello@exa.ai for Enterprise plans.

Rate Limit Structure

Prerequisites

• exa-js SDK installed
• Understanding of async/await patterns

Instructions

Step 1: Exponential Backoff with Jitter

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

async function withBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err: any) {
      const status = err.status || err.response?.status;
      // Only retry on 429 (rate limit) and 5xx (server errors)
      if (status !== 429 && (status < 500 || status >= 600)) throw err;
      if (attempt === config.maxRetries) throw err;

      // Exponential delay with random jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * 500;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`[Exa] ${status} — retry ${attempt + 1}/${config.maxRetries} in ${delay.toFixed(0)}ms`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

// Usage
const results = await withBackoff(() =>
  exa.searchAndContents("AI research", { numResults: 5, text: true })
);

Step 2: Request Queue with Concurrency Control

import PQueue from "p-queue";

// Limit to 8 concurrent requests (under the 10 QPS limit)
const exaQueue = new PQueue({
  concurrency: 8,
  interval: 1000,    // per second
  intervalCap: 10,   // max 10 per interval (matches

Exa Reference Architecture

Prerequisites

• An approved search/research data flow, policy/data classification, environment boundaries, and owner for each integration point.
• Reviewed interfaces for credentials, retrieval controls, result handling, observability, automation, and incident response.

Output

• A documented architecture with trust boundaries, ownership, source/citation controls, redacted telemetry, and reversible integration points.

Examples

Model a development client that receives sanitized queries, applies approved source/date constraints, records only aggregate/correlation metadata, and returns results for human review. Promote the versioned contract through staging before production automation; keep policy guardrails and fallback behavior explicit rather than treating retrieval output as authoritative.

Overview

Production architecture for Exa neural search integration. Covers search service design, content extraction pipeline, RAG integration, domain-scoped search profiles, and caching strategy.

Architecture Diagram

┌──────────────────────────────────────────────────────────┐
│                  Application Layer                        │
│   RAG Pipeline  |  Research Agent  |  Content Discovery   │
└──────────┬──────────────┬───────────────┬────────────────┘
           │              │               │
           ▼              ▼               ▼
┌──────────────────────────────────────────────────────────┐
│                Exa Search Service Layer                    │
│  ┌────────────┐  ┌────────────┐  ┌──────────────────┐    │
│  │ search()   │  │ findSimilar│  │ getContents()    │    │
│  │ neural/    │  │ (URL seed) │  │ (known URLs)     │    │
│  │ keyword/   │  └────────────┘  └──────────────────┘    │
│  │ auto/fast  │                                           │
│  └────────────┘                  ┌──────────────────┐    │
│                                  │ answer() /       │    │
│  Content Options:                │ streamAnswer()   │    │
│  text | highlights | summary     └──────────────────┘    │
│                                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │              Result Cache (LRU + Redis)             │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────────┐
│  api.exa.ai — Exa Neural Search API                      │
│  Auth: x-api-key header | Rate: 10 QPS default           │
└──────────────────────────────────────────────────────────┘

Instructions

Step 1: Search Service Layer

// src/exa/service.ts
import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

interface SearchRequest {
  query:

Exa Reliability Patterns

Prerequisites

• An SLO, owner, sanitized test inputs, rate/timeout policy, and a safe fallback/rollback path.
• Idempotent work tracking and redacted observability for request state and outcome.

Output

• A resilient retrieval integration with bounded retry, timeout, circuit-breaker/fallback, and incident evidence controls.

Examples

Use a sanitized query fixture to exercise timeout and transient error handling, verify exponential backoff and fallback behavior, then record aggregate completion/latency/error results. Do not retry unboundedly or turn a failed retrieval into an unreviewed automated decision.

Overview

Production reliability patterns for Exa neural search. Exa-specific failure modes include: empty result sets (query too narrow), content retrieval failures (sites block crawling), variable latency by search type, and 429 rate limits at 10 QPS default.

Instructions

Step 1: Query Fallback Chain

import Exa from "exa-js";

const exa = new Exa(process.env.EXA_API_KEY);

// If neural search returns too few results, fall back through search types
async function resilientSearch(
  query: string,
  minResults = 3,
  opts: any = {}
) {
  // Try 1: Neural search (best quality)
  let results = await exa.searchAndContents(query, {
    type: "neural",
    numResults: 10,
    ...opts,
  });
  if (results.results.length >= minResults) return results;

  // Try 2: Auto search (Exa picks best approach)
  results = await exa.searchAndContents(query, {
    type: "auto",
    numResults: 10,
    ...opts,
  });
  if (results.results.length >= minResults) return results;

  // Try 3: Keyword search (different index)
  results = await exa.searchAndContents(query, {
    type: "keyword",
    numResults: 10,
    ...opts,
  });
  if (results.results.length >= minResults) return results;

  // Try 4: Remove filters and broaden
  const broadOpts = { ...opts };
  delete broadOpts.startPublishedDate;
  delete broadOpts.endPublishedDate;
  delete broadOpts.includeDomains;
  delete broadOpts.includeText;

  return exa.searchAndContents(query, {
    type: "auto",
    numResults: 10,
    ...broadOpts,
  });
}

Step 2: Retry with Exponential Backoff

async function searchWithRetry(
  query: string,
  opts: any,
  maxRetries = 3
) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await exa.searchAndContents(query, opts);
    } catch (err: any) {
      const status = err.status || 0;

      // Only retry on rate limits (429) and server errors (5xx)
      if (status !== 429 && (status < 500 || status >= 600)) throw err;
      if (attempt === maxRetries) throw err;

      const delay = 1000 * Math.pow(2, attempt) + Math.random() * 500;
   

Exa SDK Patterns

Output

• A reusable Exa client boundary with scoped configuration, sanitized inputs, policy controls, redacted telemetry, and safe error classification.
• Unit/integration evidence that avoids real sensitive queries, result content, and credentials.

Overview

Production-ready patterns for the exa-js SDK. Covers client singletons, typed wrappers, error handling, retry logic, and response validation for real Exa API methods.

Prerequisites

• exa-js installed and EXA_API_KEY configured
• TypeScript project with strict mode
• Familiarity with async/await and error handling

Instructions

Step 1: Client Singleton

// src/exa/client.ts
import Exa from "exa-js";

let instance: Exa | null = null;

export function getExa(): Exa {
  if (!instance) {
    const apiKey = process.env.EXA_API_KEY;
    if (!apiKey) {
      throw new Error("EXA_API_KEY not set. Get one at https://dashboard.exa.ai");
    }
    instance = new Exa(apiKey);
  }
  return instance;
}

Step 2: Typed Search Wrapper

// src/exa/search.ts
import Exa from "exa-js";
import { getExa } from "./client";

interface ExaSearchOptions {
  type?: "auto" | "neural" | "keyword" | "fast" | "instant" | "deep" | "deep-reasoning";
  numResults?: number;
  includeDomains?: string[];
  excludeDomains?: string[];
  startPublishedDate?: string;
  endPublishedDate?: string;
  category?: "company" | "research paper" | "news" | "tweet" | "personal site" | "financial report" | "people";
  includeText?: string[];
  excludeText?: string[];
}

interface ExaContentsOptions {
  text?: boolean | { maxCharacters?: number; includeHtmlTags?: boolean };
  highlights?: boolean | { maxCharacters?: number; query?: string };
  summary?: boolean | { query?: string };
  livecrawl?: "always" | "preferred" | "fallback" | "never";
  livecrawlTimeout?: number;
  subpages?: number;
  subpageTarget?: string | string[];
}

export async function exaSearch(query: string, opts: ExaSearchOptions = {}) {
  const exa = getExa();
  return exa.search(query, {
    type: opts.type ?? "auto",
    numResults: opts.numResults ?? 10,
    ...opts,
  });
}

export async function exaSearchWithContents(
  query: string,
  searchOpts: ExaSearchOptions = {},
  contentOpts: ExaContentsOptions = {}
) {
  const exa = getExa();
  return exa.searchAndContents(query, {
    type: searchOpts.type ?? "auto",
    numResults: searchOpts.numResults ?? 10,
    ...searchOpts,
    ...contentOpts,
  });
}

Step 3: Error Handling Wrapper

                

                  
                    
                  
                  exa-security-basics
                  View full skill →
                
                

                  
Secure Exa API keys, implement content moderation, and manage domain restrictions.
                  

                      ReadWriteGrep
                    
                
                

                  
Exa Security Basics
Output

A least-privilege Exa integration with scoped credentials, approved data boundaries, policy enforcement, and incident/revocation ownership.
A tested security boundary for secrets, private queries/results, automation scope, and redacted logging.

Overview
Security best practices for Exa API integrations. Exa authenticates via the x-api-key header. Key security concerns include API key protection, content moderation for search results, domain filtering to prevent exposure to malicious sources, and query sanitization.
Prerequisites

Exa API key from dashboard.exa.ai
Understanding of environment variable management
.gitignore configured for secrets

Instructions
Step 1: API Key Management

# .env (NEVER commit to git)
EXA_API_KEY=your-api-key-here

# .gitignore — add these entries
.env
.env.local
.env.*.local


// Validate API key exists before creating client
import Exa from "exa-js";

function createSecureClient(): Exa {
  const apiKey = process.env.EXA_API_KEY;
  if (!apiKey) {
    throw new Error("EXA_API_KEY not configured");
  }
  if (apiKey.startsWith("sk_") && apiKey.length < 20) {
    throw new Error("EXA_API_KEY appears malformed");
  }
  return new Exa(apiKey);
}

Step 2: Enable Content Moderation

const exa = new Exa(process.env.EXA_API_KEY);

// Exa supports content moderation to filter unsafe results
const results = await exa.searchAndContents(
  "user-provided search query",
  {
    numResults: 10,
    text: true,
    moderation: true,  // filter unsafe content from results
  }
);

Step 3: Domain Filtering for Safety

// Restrict results to trusted domains for sensitive use cases
const TRUSTED_DOMAINS = [
  "docs.python.org", "developer.mozilla.org", "nodejs.org",
  "github.com", "stackoverflow.com", "arxiv.org",
];

const BLOCKED_DOMAINS = [
  "known-malware-site.com", "phishing-domain.net",
];

async function safeDomainSearch(query: string) {
  return exa.searchAndContents(query, {
    numResults: 10,
    includeDomains: TRUSTED_DOMAINS,  // only return results from these
    text: { maxCharacters: 1000 },
  });
}

async function searchWithBlocklist(query: string) {
  return exa.searchAndContents(query, {
    numResults: 10,
    excludeDomains: BLOCKED_DOMAINS,  // never return results from these
    text: { maxCharacters: 1000 },
  });
}

Step 4: Query Sanitization

// Sanitize user-provided queries before sending to Exa
function sanitizeQuery(input: string): string {
  // Remove p