Exa Research

Exa Research & Answer API

Quick Reference

Essential Patterns

Answer API (Python)

from exa_py import Exa

exa = Exa()

response = exa.answer(
    "What are the key features of Python 3.12?",
    text=True
)

print(response.answer)
for citation in response.citations:
    print(f"Source: {citation.url}")

Streaming Answers

stream = exa.answer(
    "Explain the benefits of microservices architecture",
    stream=True
)

for chunk in stream:
    print(chunk.text, end="", flush=True)

# Access citations after streaming
print("\nSources:", stream.citations)

Deep Search with Summaries

results = exa.search_and_contents(
    "latest developments in quantum computing",
    type="neural",
    num_results=10,
    summary=True,
    use_autoprompt=True  # Smart query expansion
)

for result in results.results:
    print(f"{result.title}")
    print(f"Summary: {result.summary}")

When to Use

Common Mistakes

1. Not using streaming for long answers - Use stream=True for better UX on complex questions 2. Ignoring citations - Always include response.citations for verifiable responses 3. Missing `text=True` - Answer API needs content access; include text=True 4. Over-complex queries - Answer API works best with clear, focused questions 5. Not validating citations - Check citation.url exists before displaying to users

Answer API Reference

Table of Contents

• Basic Usage
• Streaming Responses
• Configuration Options
• Response Structure
• Best Practices

---

Basic Usage

The Answer API generates LLM responses with citations from web search results.

Python

from exa_py import Exa

exa = Exa()  # Uses EXA_API_KEY env var

response = exa.answer(
    "What are the key differences between React and Vue?",
    text=True
)

print("Answer:", response.answer)
print("\nSources:")
for citation in response.citations:
    print(f"- {citation.title}: {citation.url}")

TypeScript

import Exa from "exa-js";

const exa = new Exa();

const response = await exa.answer(
  "What are the key differences between React and Vue?",
  { text: true }
);

console.log("Answer:", response.answer);
console.log("Sources:", response.citations.map((c) => c.url));

With Search Filters

response = exa.answer(
    "What's new in TypeScript 5.4?",
    text=True,
    include_domains=["devblogs.microsoft.com", "typescriptlang.org"],
    start_published_date="2024-01-01"
)

---

Streaming Responses

For better UX on complex questions, use streaming.

Python Streaming

stream = exa.answer(
    "Explain the transformer architecture in detail",
    text=True,
    stream=True
)

# Stream the answer text
for chunk in stream:
    if chunk.text:
        print(chunk.text, end="", flush=True)

# Access citations after streaming completes
print("\n\nSources:")
for citation in stream.citations:
    print(f"- {citation.url}")

TypeScript Streaming

const stream = await exa.answer(
  "Explain the transformer architecture in detail",
  { text: true, stream: true }
);

for await (const chunk of stream) {
  if (chunk.text) {
    process.stdout.write(chunk.text);
  }
}

// Citations available after stream ends
console.log("\nSources:", stream.citations);

Streaming with Progress

def answer_with_progress(question):
    stream = exa.answer(question, text=True, stream=True)

    full_answer = ""
    for chunk in stream:
        if chunk.text:
            full_answer += chunk.text
            print(chunk.text, end="", flush=True)

    return {
        "answer": full_answer,
        "citations": stream.citations
    }

---

Configuration Options

Available Parameters

Example with All Options

response = exa.answer(
    "What are the latest best practices for API security?",
    text=True,
    stream=False,
    include_domains=["owasp.org", "auth0.com", "cloudflare.com"],
    start_published_date="2024-01-01",
    num_results=10
)

---

Response Structure

Non-Streaming Response

response = exa.answer("question", text=True)

# Answer text
response.answer  # str: The generated answer

# Citations
response.citations  # list[Citation]

# Each citation
for citation in response.citations:
    citation.url        # str: Source URL
    citation.title      # str: Page title
    citation.text       # str: Relevant text (if text=True)
    citation.highlights # list[str]: Key snippets

Streaming Response

stream = exa.answer("question", text=True, stream=True)

# Iterate chunks
for chunk in stream:
    chunk.text  # str: Partial answer text

# After iteration
stream.citations  # list[Citation]: Available after stream ends
stream.answer     # str: Complete answer

---

Best Practices

Ask Focused Questions

# Good: Specific, focused question
response = exa.answer(
    "What are the three main benefits of using TypeScript over JavaScript?",
    text=True
)

# Avoid: Too broad
response = exa.answer(
    "Tell me everything about TypeScript",
    text=True
)

Filter for Authoritative Sources

response = exa.answer(
    "What are React Server Components?",
    text=True,
    include_domains=["react.dev", "nextjs.org", "vercel.com"]
)

Handle Missing Citations

response = exa.answer("question", text=True)

if response.citations:
    print("Answer:", response.answer)
    print("Sources:")
    for c in response.citations:
        print(f"- {c.url}")
else:
    print("Answer (unverified):", response.answer)
    print("Warning: No citations available")

Combine with Follow-up Search

def research_topic(question):
    # Get initial answer
    answer = exa.answer(question, text=True)

    # If more detail needed, search for related content
    if len(answer.citations) < 3:
        additional = exa.search_and_contents(
            question,
            num_results=5,
            text=True,
            exclude_domains=[c.url for c in answer.citations]
        )
        return {
            "answer": answer.answer,
            "primary_sources": answer.citations,
            "additional_sources": additional.results
        }

    return {"answer": answer.answer, "sources": answer.citations}

Error Handling

from exa_py.exceptions import ExaError

try:
    response = exa.answer(
        "What is the latest version of Node.js?",
        text=True
    )
except ExaError as e:
    print(f"Answer API error: {e}")
    # Fall back to regular search
    results = exa.search_and_contents(
        "latest Node.js version",
        num_results=5,
        text=True
    )

Citations Reference

Table of Contents

• Citation Structure
• Extracting Citations
• Citation Display Patterns
• Verification
• Attribution Best Practices

---

Citation Structure

From Answer API

response = exa.answer("What is RAG?", text=True)

for citation in response.citations:
    print(f"URL: {citation.url}")
    print(f"Title: {citation.title}")
    print(f"Text: {citation.text}")  # If text=True
    print(f"Highlights: {citation.highlights}")

From Search Results

results = exa.search_and_contents("topic", text=True, highlights=True)

for result in results.results:
    citation = {
        "url": result.url,
        "title": result.title,
        "published_date": result.published_date,
        "author": result.author,
        "text": result.text,
        "highlights": result.highlights
    }

---

Extracting Citations

From Answer Response

def extract_citations(answer_response):
    """Extract structured citations from answer."""
    return [
        {
            "id": i + 1,
            "url": c.url,
            "title": c.title or "Untitled",
            "snippet": c.highlights[0] if c.highlights else c.text[:200] if c.text else ""
        }
        for i, c in enumerate(answer_response.citations)
    ]

response = exa.answer("What are microservices?", text=True)
citations = extract_citations(response)

From Search Results

def search_with_citations(query, num_results=5):
    """Search and return structured citations."""
    results = exa.search_and_contents(
        query,
        num_results=num_results,
        text=True,
        highlights=True
    )

    return {
        "results": results.results,
        "citations": [
            {
                "id": i + 1,
                "url": r.url,
                "title": r.title,
                "date": r.published_date,
                "snippet": r.highlights[0] if r.highlights else r.text[:200] if r.text else ""
            }
            for i, r in enumerate(results.results)
        ]
    }

---

Citation Display Patterns

Inline Citations

def format_answer_with_inline_citations(response):
    """Format answer with numbered inline citations."""
    answer = response.answer
    citations = response.citations

    # Add citation numbers to answer (simplified)
    formatted = answer
    for i, citation in enumerate(citations):
        formatted += f" [{i + 1}]"

    # Build references section
    references = "\n\nReferences:\n"
    for i, c in enumerate(citations):
        references += f"[{i + 1}] {c.title} - {c.url}\n"

    return formatted + references

Academic Style

def academic_citation(citation, style="apa"):
    """Format citation in academic style."""
    if style == "apa":
        author = citation.author or "Unknown Author"
        date = citation.published_date[:4] if citation.published_date else "n.d."
        title = citation.title
        url = citation.url
        return f"{author} ({date}). {title}. Retrieved from {url}"

    elif style == "mla":
        author = citation.author or "Unknown Author"
        title = f'"{citation.title}"'
        url = citation.url
        return f'{author}. {title}. Web. <{url}>'

Markdown Format

def citations_to_markdown(citations):
    """Convert citations to markdown format."""
    md = "## Sources\n\n"

    for i, c in enumerate(citations):
        title = c.title or c.url
        url = c.url
        snippet = c.highlights[0] if c.highlights else ""

        md += f"{i + 1}. [{title}]({url})\n"
        if snippet:
            md += f"   > {snippet[:150]}...\n"
        md += "\n"

    return md

HTML Format

def citations_to_html(citations):
    """Convert citations to HTML list."""
    html = '<ol class="citations">\n'

    for c in citations:
        title = c.title or "Untitled"
        url = c.url

        html += f'  <li>\n'
        html += f'    <a href="{url}" target="_blank">{title}</a>\n'
        if c.published_date:
            html += f'    <span class="date">({c.published_date})</span>\n'
        html += f'  </li>\n'

    html += '</ol>'
    return html

---

Verification

URL Validation

from urllib.parse import urlparse

def validate_citation(citation):
    """Validate citation has required fields."""
    issues = []

    # Check URL
    if not citation.url:
        issues.append("Missing URL")
    else:
        parsed = urlparse(citation.url)
        if not parsed.scheme or not parsed.netloc:
            issues.append("Invalid URL format")

    # Check title
    if not citation.title:
        issues.append("Missing title")

    return {
        "valid": len(issues) == 0,
        "issues": issues
    }

def filter_valid_citations(citations):
    """Return only valid citations."""
    return [c for c in citations if validate_citation(c)["valid"]]

Content Verification

def verify_citation_content(citation, claim):
    """Verify citation supports the claim."""
    if not citation.text and not citation.highlights:
        return {"verified": False, "reason": "No content to verify"}

    content = citation.text or " ".join(citation.highlights)

    # Simple keyword overlap check
    claim_words = set(claim.lower().split())
    content_words = set(content.lower().split())
    overlap = claim_words & content_words

    relevance = len(overlap) / len(claim_words) if claim_words else 0

    return {
        "verified": relevance > 0.3,
        "relevance_score": relevance,
        "matching_terms": list(overlap)
    }

Freshness Check

from datetime import datetime, timedelta

def check_citation_freshness(citation, max_age_days=365):
    """Check if citation is recent enough."""
    if not citation.published_date:
        return {"fresh": None, "reason": "No date available"}

    try:
        pub_date = datetime.fromisoformat(citation.published_date[:10])
        age = datetime.now() - pub_date
        is_fresh = age.days <= max_age_days

        return {
            "fresh": is_fresh,
            "age_days": age.days,
            "published": citation.published_date
        }
    except ValueError:
        return {"fresh": None, "reason": "Invalid date format"}

---

Attribution Best Practices

Always Include Sources

def generate_response_with_sources(question):
    """Always include sources in response."""
    response = exa.answer(question, text=True)

    output = f"Answer: {response.answer}\n\n"

    if response.citations:
        output += "Sources:\n"
        for c in response.citations:
            output += f"- {c.title}: {c.url}\n"
    else:
        output += "Note: This response could not be verified with sources.\n"

    return output

Distinguish Primary vs Supporting Sources

def categorize_sources(answer_citations, search_results):
    """Categorize sources by relevance."""
    return {
        "primary_sources": [
            {"title": c.title, "url": c.url}
            for c in answer_citations[:3]
        ],
        "supporting_sources": [
            {"title": r.title, "url": r.url}
            for r in search_results
            if r.url not in [c.url for c in answer_citations]
        ]
    }

Handle Missing Citations Gracefully

def safe_citation_display(response):
    """Handle cases with no or few citations."""
    answer = response.answer
    citations = response.citations or []

    if len(citations) == 0:
        return {
            "answer": answer,
            "confidence": "low",
            "warning": "No sources found to verify this information",
            "citations": []
        }
    elif len(citations) < 3:
        return {
            "answer": answer,
            "confidence": "medium",
            "note": "Limited sources available",
            "citations": citations
        }
    else:
        return {
            "answer": answer,
            "confidence": "high",
            "citations": citations
        }

Deep Search Reference

Table of Contents

• Overview
• Smart Query Expansion
• Summaries
• Deep Search Patterns
• Exa Research API

---

Overview

Deep Search provides enhanced search capabilities with:

• Smart query expansion (autoprompt)
• High-quality AI summaries
• Better results for complex queries

---

Smart Query Expansion

Exa can automatically expand your query for better results.

Autoprompt (Deprecated but Functional)

from exa_py import Exa

exa = Exa()

# Autoprompt expands the query intelligently
results = exa.search_and_contents(
    "best practices for building APIs",
    type="neural",
    use_autoprompt=True,
    num_results=10,
    text=True
)

# Check expanded query
print(f"Expanded query: {results.autoprompt_string}")

Manual Query Enhancement

def enhance_query(base_query, context=None):
    """Enhance query for better search results."""
    if context:
        return f"{base_query} {context}"

    # Add common enhancers based on query type
    if "how to" in base_query.lower():
        return f"{base_query} tutorial guide example"
    elif "best" in base_query.lower():
        return f"{base_query} comparison review 2024"

    return base_query

results = exa.search_and_contents(
    enhance_query("how to implement OAuth"),
    type="neural",
    num_results=10
)

---

Summaries

AI-generated summaries provide concise context without full page text.

Basic Summary Usage

results = exa.search_and_contents(
    "microservices architecture patterns",
    type="neural",
    num_results=10,
    summary=True  # Get AI-generated summaries
)

for result in results.results:
    print(f"Title: {result.title}")
    print(f"Summary: {result.summary}")
    print(f"URL: {result.url}\n")

Summaries with Highlights

results = exa.search_and_contents(
    "kubernetes deployment strategies",
    type="neural",
    num_results=10,
    summary=True,
    highlights=True
)

for result in results.results:
    print(f"Title: {result.title}")
    print(f"Summary: {result.summary}")
    print("Key points:")
    for h in result.highlights:
        print(f"  - {h}")

Summary vs Text vs Highlights

# Token-efficient: summaries only
results = exa.search_and_contents(query, summary=True, num_results=5)

# Balanced: summaries + highlights
results = exa.search_and_contents(query, summary=True, highlights=True, num_results=5)

# Complete: full text
results = exa.search_and_contents(query, text=True, num_results=5)

---

Deep Search Patterns

Research Deep Dive

def deep_research(topic, num_results=20):
    """Comprehensive research on a topic."""
    results = exa.search_and_contents(
        topic,
        type="neural",
        num_results=num_results,
        summary=True,
        highlights=True,
        text={"max_characters": 2000}
    )

    research = {
        "topic": topic,
        "sources": [],
        "key_points": []
    }

    for result in results.results:
        research["sources"].append({
            "title": result.title,
            "url": result.url,
            "summary": result.summary,
            "key_points": result.highlights
        })
        research["key_points"].extend(result.highlights or [])

    return research

Multi-Angle Research

def multi_angle_research(topic):
    """Research topic from multiple angles."""
    angles = [
        f"{topic} benefits advantages",
        f"{topic} challenges problems",
        f"{topic} best practices",
        f"{topic} examples case studies"
    ]

    all_results = {}
    for angle in angles:
        results = exa.search_and_contents(
            angle,
            type="neural",
            num_results=5,
            summary=True
        )
        all_results[angle] = results.results

    return all_results

Temporal Research

def research_over_time(topic, years=[2022, 2023, 2024]):
    """Track topic evolution over time."""
    timeline = {}

    for year in years:
        results = exa.search_and_contents(
            topic,
            type="neural",
            num_results=5,
            summary=True,
            start_published_date=f"{year}-01-01",
            end_published_date=f"{year}-12-31"
        )
        timeline[year] = [
            {"title": r.title, "summary": r.summary, "url": r.url}
            for r in results.results
        ]

    return timeline

---

Exa Research API

For long-form async research tasks producing structured reports.

Basic Research Task

# Start async research task
task = exa.research(
    "Comprehensive analysis of AI agent frameworks in 2024",
    output_format="markdown"
)

# Poll for completion
import time
while task.status != "completed":
    time.sleep(5)
    task = exa.get_research_task(task.id)

# Get results
print(task.result)  # Markdown report with citations

Research with JSON Output

task = exa.research(
    "Compare the top 5 vector databases",
    output_format="json",
    schema={
        "type": "object",
        "properties": {
            "databases": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "pros": {"type": "array"},
                        "cons": {"type": "array"},
                        "use_cases": {"type": "array"}
                    }
                }
            }
        }
    }
)

Research Task Management

# List active tasks
tasks = exa.list_research_tasks()

# Cancel a task
exa.cancel_research_task(task_id)

# Get specific task
task = exa.get_research_task(task_id)
print(f"Status: {task.status}")  # pending, running, completed, failed
print(f"Progress: {task.progress}%")

---

Combining Deep Search with Answer API

def comprehensive_answer(question):
    """Get answer with deep supporting research."""

    # Get direct answer
    answer_response = exa.answer(question, text=True)

    # Get additional context with deep search
    deep_results = exa.search_and_contents(
        question,
        type="neural",
        num_results=10,
        summary=True,
        highlights=True
    )

    return {
        "answer": answer_response.answer,
        "primary_citations": answer_response.citations,
        "supporting_research": [
            {
                "title": r.title,
                "url": r.url,
                "summary": r.summary,
                "key_points": r.highlights
            }
            for r in deep_results.results
        ]
    }