Exa Search

Exa Search Integration

Quick Reference

Essential Patterns

Basic Search (Python)

from exa_py import Exa

exa = Exa(api_key="your-api-key")  # or set EXA_API_KEY env var

results = exa.search_and_contents(
    "latest developments in quantum computing",
    type="auto",
    num_results=10,
    text=True,
    highlights=True
)

for result in results.results:
    print(f"{result.title}: {result.url}")
    print(result.text[:500])

Basic Search (TypeScript)

import Exa from "exa-js";

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

const results = await exa.searchAndContents(
  "latest developments in quantum computing",
  {
    type: "auto",
    numResults: 10,
    text: true,
    highlights: true,
  }
);

results.results.forEach((result) => {
  console.log(`${result.title}: ${result.url}`);
});

Search with Filters

results = exa.search_and_contents(
    "AI startup funding rounds",
    type="neural",
    num_results=10,
    include_domains=["techcrunch.com", "venturebeat.com"],
    start_published_date="2024-01-01",
    text={"max_characters": 2000},
    summary=True
)

Find Similar Links

similar = exa.find_similar_and_contents(
    "https://example.com/interesting-article",
    num_results=10,
    exclude_source_domain=True,
    text=True
)

Search Mode Selection

Common Mistakes

1. Using `keyword` for conceptual queries - Neural search understands intent better; use auto or neural for natural language questions 2. Not setting `text=True` - Search returns URLs only by default; explicitly request content with text=True 3. Ignoring `highlights` - Use highlights=True for relevant snippets without downloading full page text 4. Missing API key - Set EXA_API_KEY environment variable or pass explicitly to constructor 5. Over-filtering initially - Start with broad searches, then add domain/date filters to refine 6. Not using `summary` - For RAG applications, summary=True provides concise context without full page text 7. Expecting scores in auto mode - Relevance scores are only returned with type="neural"; auto mode doesn't include them

Contents Retrieval Reference

Table of Contents

• Content Options Overview
• Text Extraction
• Highlights
• Summaries
• Livecrawl Options
• Contents Endpoint

---

Content Options Overview

When using search_and_contents() or searchAndContents(), specify what content to retrieve:

---

Text Extraction

Basic Text Retrieval

results = exa.search_and_contents(
    "Python best practices",
    text=True,  # Returns full text
    num_results=5
)

for result in results.results:
    print(result.text)  # Full page content

Limit Text Length

# Limit to 1000 characters per result
results = exa.search_and_contents(
    "Python best practices",
    text={"max_characters": 1000},
    num_results=5
)

const results = await exa.searchAndContents("Python best practices", {
  text: { maxCharacters: 1000 },
  numResults: 5,
});

Text Format

Exa returns content in Markdown format by default, optimized for AI consumption.

# Result text is markdown-formatted
print(result.text)
# Output: "# Page Title\n\nParagraph content...\n\n## Section..."

---

Highlights

Highlights return the most relevant snippets from the page matching your query.

Basic Highlights

results = exa.search_and_contents(
    "React hooks tutorial",
    highlights=True,
    num_results=5
)

for result in results.results:
    for highlight in result.highlights:
        print(highlight)  # Relevant snippet

Highlight Options

results = exa.search_and_contents(
    "React hooks tutorial",
    highlights={
        "num_sentences": 3,  # Sentences per highlight
        "highlights_per_url": 3  # Max highlights per result
    },
    num_results=5
)

const results = await exa.searchAndContents("React hooks tutorial", {
  highlights: {
    numSentences: 3,
    highlightsPerUrl: 3,
  },
  numResults: 5,
});

When to Use Highlights

• RAG applications needing relevant context
• Search result previews
• When full text is too large
• Extracting key information quickly

---

Summaries

AI-generated summaries of page content.

Usage

results = exa.search_and_contents(
    "machine learning frameworks comparison",
    summary=True,
    num_results=5
)

for result in results.results:
    print(result.summary)  # AI-generated summary

const results = await exa.searchAndContents(
  "machine learning frameworks comparison",
  { summary: true, numResults: 5 }
);

Best Practices

• Use for RAG when full context not needed
• Combine with highlights for comprehensive context
• More token-efficient than full text

---

Livecrawl Options

Control how Exa fetches fresh content.

Livecrawl Modes

Usage

# Always get fresh content
results = exa.search_and_contents(
    "breaking tech news",
    livecrawl="always",
    text=True,
    num_results=5
)

# Prefer fresh but accept cached
results = exa.search_and_contents(
    "company updates",
    livecrawl="preferred",
    text=True,
    num_results=5
)

const results = await exa.searchAndContents("breaking tech news", {
  livecrawl: "always",
  text: true,
  numResults: 5,
});

When to Use Each Mode

• never: Historical research, reproducible results
• fallback: General use, balance of speed and freshness
• preferred: News, rapidly changing content
• always: Real-time monitoring, critical freshness

---

Contents Endpoint

Retrieve contents for known URLs without searching.

Usage

# Get contents for specific URLs
contents = exa.get_contents(
    urls=["https://example.com/article1", "https://example.com/article2"],
    text=True,
    summary=True
)

for content in contents.results:
    print(f"{content.title}: {content.summary}")

const contents = await exa.getContents(
  ["https://example.com/article1", "https://example.com/article2"],
  { text: true, summary: true }
);

Use Cases

• Fetch content for URLs from other sources
• Update cached content
• Batch content retrieval

Response Status

Contents endpoint returns detailed status instead of HTTP errors:

for content in contents.results:
    if content.text:
        print(content.text)
    else:
        print(f"Status: {content.status_code}")  # e.g., 404, timeout

---

Combining Content Options

Full Context Retrieval

results = exa.search_and_contents(
    "GraphQL vs REST API comparison",
    text={"max_characters": 5000},
    highlights={"num_sentences": 2, "highlights_per_url": 3},
    summary=True,
    num_results=10
)

for result in results.results:
    print(f"Title: {result.title}")
    print(f"URL: {result.url}")
    print(f"Summary: {result.summary}")
    print("Highlights:")
    for h in result.highlights:
        print(f"  - {h}")
    print(f"Full text: {result.text[:500]}...")

Token-Efficient Retrieval

# For RAG with limited context window
results = exa.search_and_contents(
    "query",
    highlights={"num_sentences": 2, "highlights_per_url": 2},
    summary=True,
    # Skip full text to save tokens
    num_results=5
)

Search Filters Reference

Table of Contents

• Domain Filtering
• Date Filtering
• Text Filtering
• Category Filtering
• Geolocation Filtering
• Combining Filters

---

Domain Filtering

Include Specific Domains

Limit results to specific websites.

results = exa.search_and_contents(
    "machine learning tutorials",
    include_domains=["github.com", "medium.com", "dev.to"],
    num_results=10
)

const results = await exa.searchAndContents("machine learning tutorials", {
  includeDomains: ["github.com", "medium.com", "dev.to"],
  numResults: 10,
});

Exclude Domains

Filter out unwanted sources.

results = exa.search_and_contents(
    "python programming",
    exclude_domains=["pinterest.com", "facebook.com", "twitter.com"],
    num_results=10
)

Subdomain Wildcards

Match all subdomains of a domain.

# Matches docs.github.com, gist.github.com, etc.
results = exa.search_and_contents(
    "GitHub Actions examples",
    include_domains=["*.github.com"],
    num_results=10
)

---

Date Filtering

Published Date Range

Filter by when content was published.

results = exa.search_and_contents(
    "AI developments",
    start_published_date="2024-01-01",
    end_published_date="2024-12-31",
    num_results=10
)

const results = await exa.searchAndContents("AI developments", {
  startPublishedDate: "2024-01-01",
  endPublishedDate: "2024-12-31",
  numResults: 10,
});

Crawl Date Range

Filter by when Exa indexed the page (useful for finding recently discovered content).

results = exa.search_and_contents(
    "new JavaScript frameworks",
    start_crawl_date="2024-06-01",
    num_results=10
)

Date Format

• Use ISO 8601 format: YYYY-MM-DD
• Timestamps also supported: 2024-01-01T00:00:00Z

---

Text Filtering

Include Text

Results must contain all specified strings.

results = exa.search_and_contents(
    "web development",
    include_text=["React", "TypeScript"],
    num_results=10
)

const results = await exa.searchAndContents("web development", {
  includeText: ["React", "TypeScript"],
  numResults: 10,
});

Exclude Text

Filter out results containing specified strings.

results = exa.search_and_contents(
    "JavaScript tutorials",
    exclude_text=["advertisement", "sponsored", "affiliate"],
    num_results=10
)

Text Filter Best Practices

• Use for required technical terms
• Helps narrow broad queries
• Case-insensitive matching
• Combine with domain filters for precision

---

Category Filtering

Pre-defined categories for specialized searches.

Available Categories

Usage

# Company search
results = exa.search_and_contents(
    "AI startups healthcare",
    category="company",
    num_results=10
)

# Research papers
results = exa.search_and_contents(
    "transformer architecture improvements",
    category="research_paper",
    num_results=10
)

# GitHub repositories
results = exa.search_and_contents(
    "React component library",
    category="github",
    num_results=10
)

const results = await exa.searchAndContents("AI startups healthcare", {
  category: "company",
  numResults: 10,
});

---

Geolocation Filtering

Filter by user location for localized results.

results = exa.search_and_contents(
    "coffee shops",
    user_location={
        "latitude": 37.7749,
        "longitude": -122.4194,
        "radius_miles": 10
    },
    num_results=10
)

Language Filtering

Exa auto-detects query language and filters results accordingly. This is enabled by default.

# Disable language filtering to get results in all languages
results = exa.search_and_contents(
    "machine learning",
    filter_language=False,
    num_results=10
)

---

Combining Filters

Complex Filter Example

results = exa.search_and_contents(
    "Series A funding announcement",
    type="neural",
    category="news",
    include_domains=["techcrunch.com", "venturebeat.com", "bloomberg.com"],
    exclude_text=["sponsored"],
    start_published_date="2024-01-01",
    num_results=20,
    text=True,
    summary=True
)

const results = await exa.searchAndContents("Series A funding announcement", {
  type: "neural",
  category: "news",
  includeDomains: ["techcrunch.com", "venturebeat.com", "bloomberg.com"],
  excludeText: ["sponsored"],
  startPublishedDate: "2024-01-01",
  numResults: 20,
  text: true,
  summary: true,
});

Filter Priority Tips

1. Start broad, then narrow with filters 2. Category filters are highly optimized - use when applicable 3. Domain filters reduce noise effectively 4. Date filters essential for time-sensitive content 5. Text filters for required technical terms

SDK Patterns Reference

Table of Contents

• Installation
• Authentication
• Python SDK (exa_py)
• TypeScript SDK (exa-js)
• Error Handling
• Response Objects

---

Installation

Python

pip install exa_py

TypeScript/JavaScript

npm install exa-js
# or
yarn add exa-js
# or
pnpm add exa-js

---

Authentication

Environment Variable (Recommended)

export EXA_API_KEY="your-api-key"

Python

from exa_py import Exa

# Uses EXA_API_KEY env var automatically
exa = Exa()

# Or pass explicitly
exa = Exa(api_key="your-api-key")

TypeScript

import Exa from "exa-js";

// Uses EXA_API_KEY env var automatically
const exa = new Exa();

// Or pass explicitly
const exa = new Exa("your-api-key");

---

Python SDK (exa_py)

Search Methods

from exa_py import Exa

exa = Exa()

# Search only (returns URLs, no content)
results = exa.search(
    "query",
    type="auto",
    num_results=10
)

# Search with contents (most common)
results = exa.search_and_contents(
    "query",
    type="auto",
    num_results=10,
    text=True,
    highlights=True,
    summary=True
)

# Find similar to a URL
similar = exa.find_similar(
    "https://example.com/article",
    num_results=10
)

# Find similar with contents
similar = exa.find_similar_and_contents(
    "https://example.com/article",
    num_results=10,
    text=True,
    exclude_source_domain=True
)

# Get contents for known URLs
contents = exa.get_contents(
    urls=["https://example.com/page1", "https://example.com/page2"],
    text=True
)

Async Support

import asyncio
from exa_py import Exa

async def search_async():
    exa = Exa()

    # All methods have async versions
    results = await exa.search_and_contents_async(
        "async programming patterns",
        num_results=10,
        text=True
    )
    return results

results = asyncio.run(search_async())

Parameter Naming Convention

Python SDK uses snake_case:

• num_results
• include_domains
• exclude_domains
• start_published_date
• include_text
• max_characters

---

TypeScript SDK (exa-js)

Search Methods

import Exa from "exa-js";

const exa = new Exa();

// Search only
const results = await exa.search("query", {
  type: "auto",
  numResults: 10,
});

// Search with contents
const results = await exa.searchAndContents("query", {
  type: "auto",
  numResults: 10,
  text: true,
  highlights: true,
  summary: true,
});

// Find similar
const similar = await exa.findSimilar("https://example.com/article", {
  numResults: 10,
});

// Find similar with contents
const similar = await exa.findSimilarAndContents(
  "https://example.com/article",
  {
    numResults: 10,
    text: true,
    excludeSourceDomain: true,
  }
);

// Get contents
const contents = await exa.getContents(
  ["https://example.com/page1", "https://example.com/page2"],
  { text: true }
);

Parameter Naming Convention

TypeScript SDK uses camelCase:

• numResults
• includeDomains
• excludeDomains
• startPublishedDate
• includeText
• maxCharacters

---

Error Handling

Python

from exa_py import Exa
from exa_py.exceptions import ExaError, RateLimitError, AuthenticationError

exa = Exa()

try:
    results = exa.search_and_contents("query", num_results=10)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded, retry later")
except ExaError as e:
    print(f"Exa error: {e}")

TypeScript

import Exa from "exa-js";

const exa = new Exa();

try {
  const results = await exa.searchAndContents("query", { numResults: 10 });
} catch (error) {
  if (error.status === 401) {
    console.log("Invalid API key");
  } else if (error.status === 429) {
    console.log("Rate limit exceeded");
  } else {
    console.log(`Error: ${error.message}`);
  }
}

---

Response Objects

Search Result Structure

# Python
result.url         # str: Page URL
result.title       # str: Page title
result.score       # float: Relevance score (neural only)
result.published_date  # str: Publication date
result.author      # str: Author if available
result.text        # str: Full text (if requested)
result.highlights  # list[str]: Relevant snippets (if requested)
result.summary     # str: AI summary (if requested)

// TypeScript
result.url; // string
result.title; // string
result.score; // number (neural only)
result.publishedDate; // string
result.author; // string
result.text; // string (if requested)
result.highlights; // string[] (if requested)
result.summary; // string (if requested)

Search Response Structure

# Python
response.results           # list[Result]: Search results
response.autoprompt_string # str: (deprecated)
response.resolved_search_type  # str: "neural" or "keyword" (auto mode)

// TypeScript
response.results; // Result[]
response.autopromptString; // string (deprecated)
response.resolvedSearchType; // string

---

Common Patterns

Pagination

# Exa doesn't support offset pagination
# Instead, use date filters or increase num_results
results = exa.search_and_contents(
    "query",
    num_results=50,  # Get more results at once
    text=True
)

Batch Processing

# Process multiple queries
queries = ["AI trends", "ML frameworks", "data science tools"]

all_results = []
for query in queries:
    results = exa.search_and_contents(query, num_results=5, text=True)
    all_results.extend(results.results)

Retry Logic

import time
from exa_py import Exa
from exa_py.exceptions import RateLimitError

def search_with_retry(query, max_retries=3):
    exa = Exa()
    for attempt in range(max_retries):
        try:
            return exa.search_and_contents(query, num_results=10, text=True)
        except RateLimitError:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

Search Modes Reference

Table of Contents

• Auto Search (Default)
• Neural Search
• Keyword Search
• Fast Search
• Mode Comparison

---

Auto Search (Default)

Auto mode intelligently selects between neural and keyword search based on query analysis.

Usage

# Python - auto is default
results = exa.search_and_contents(
    "best practices for React state management",
    type="auto",  # or omit, auto is default
    num_results=10
)

// TypeScript - auto is default
const results = await exa.searchAndContents(
  "best practices for React state management",
  { type: "auto", numResults: 10 }
);

Characteristics

• Automatically detects query intent
• Switches between neural and keyword based on query structure
• Best for general-purpose applications
• Note: Scores are not returned in auto mode

---

Neural Search

Neural search uses semantic understanding to find conceptually relevant results.

When to Use

• Natural language questions ("What is...", "How do I...")
• Topic exploration and research
• Finding related concepts
• Queries where exact terms may vary

Usage

results = exa.search_and_contents(
    "explain the benefits of microservices architecture",
    type="neural",
    num_results=10
)

# Neural search returns relevance scores
for result in results.results:
    print(f"Score: {result.score} - {result.title}")

const results = await exa.searchAndContents(
  "explain the benefits of microservices architecture",
  { type: "neural", numResults: 10 }
);

results.results.forEach((r) => console.log(`Score: ${r.score} - ${r.title}`));

Best Practices

• Use for open-ended, exploratory queries
• Leverage scores to rank results by relevance
• Combine with summary=True for RAG applications

---

Keyword Search

Keyword search finds exact term matches, similar to traditional search engines.

When to Use

• Specific product or company names
• Error codes and technical identifiers
• Exact phrase matching
• Proper nouns and named entities

Usage

results = exa.search_and_contents(
    "ECONNREFUSED Node.js",
    type="keyword",
    num_results=10
)

const results = await exa.searchAndContents("ECONNREFUSED Node.js", {
  type: "keyword",
  numResults: 10,
});

Best Practices

• Use for specific technical queries
• Ideal when you know exact terms to match
• Combine with domain filters for targeted searches

---

Fast Search

Fast search prioritizes speed over comprehensiveness.

Usage

# Use the fast search endpoint
results = exa.search(
    "breaking news technology",
    type="auto",
    num_results=5
)
# Note: search() is faster than search_and_contents()

When to Use

• Real-time applications requiring low latency
• When you only need URLs, not content
• High-volume search applications

---

Mode Comparison

Query Examples by Mode