Exa Web Search

Exa 网页搜索

Search the web using Exa's AI-powered search API. Exa provides semantic search capabilities optimized for AI applications.

使用Exa的AI驱动搜索API进行网页搜索。Exa提供针对AI应用优化的语义搜索能力。

Configuration

配置

Config file:

~/.config/exa-search/config.json

json

{
  "api_key": "your-exa-api-key-here"
}

配置文件：

~/.config/exa-search/config.json

json

{
  "api_key": "your-exa-api-key-here"
}

Getting an API key

获取API密钥

Go to https://dashboard.exa.ai/api-keys
Sign up or log in to your Exa account
Create a new API key

访问https://dashboard.exa.ai/api-keys
注册或登录你的Exa账户
创建新的API密钥

Troubleshooting config

配置故障排除

If requests fail, verify the config:

bash

undefined

如果请求失败，请验证配置：

bash

undefined

Check config exists and is valid JSON

cat ~/.config/exa-search/config.json | jq .

Test connection

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $(jq -r .api_key ~/.config/exa-search/config.json)"
-H "Content-Type: application/json"
-d '{"query": "test", "numResults": 1}' | jq '.results | length'


**Common issues:**

- `401 Unauthorized`: API key is invalid → get a new key from dashboard
- `Connection refused`: Network issue or API is down
- `null` or parse error: Config file is missing or malformed

If config is broken, guide the user to provide their Exa API key, then create/update the config:

```bash
mkdir -p ~/.config/exa-search
cat > ~/.config/exa-search/config.json << 'EOF'
{
  "api_key": "USER_PROVIDED_API_KEY"
}
EOF

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $(jq -r .api_key ~/.config/exa-search/config.json)"
-H "Content-Type: application/json"
-d '{"query": "test", "numResults": 1}' | jq '.results | length'


**常见问题：**

- `401 Unauthorized`：API密钥无效 → 从控制台获取新密钥
- `Connection refused`：网络问题或API服务中断
- `null`或解析错误：配置文件缺失或格式错误

如果配置损坏，请引导用户提供Exa API密钥，然后创建/更新配置：

```bash
mkdir -p ~/.config/exa-search
cat > ~/.config/exa-search/config.json << 'EOF'
{
  "api_key": "USER_PROVIDED_API_KEY"
}
EOF

Endpoint Selection Guide

端点选择指南

Choose the appropriate endpoint based on user intent:

Endpoint	Use When
`/search`	Need to find web pages, research topics, or get content from multiple sources
`/contents`	Have specific URLs and need to extract their full content
`/answer`	Need a direct, concise answer to a factual question
`/research/v1`	Need in-depth research with structured output, multi-step analysis, or comprehensive reports

根据用户意图选择合适的端点：

端点	适用场景
`/search`	需要查找网页、研究主题或从多来源获取内容时
`/contents`	有特定URL并需要提取其完整内容时
`/answer`	需要对事实性问题获取直接、简洁的答案时
`/research/v1`	需要进行带结构化输出的深度研究、多步骤分析或生成综合报告时

API Examples

API示例

Load API key

加载API密钥

bash

EXA_API_KEY=$(jq -r .api_key ~/.config/exa-search/config.json)

bash

EXA_API_KEY=$(jq -r .api_key ~/.config/exa-search/config.json)

1. Search (

/search

)

1. 搜索（

/search

）

Semantic search with optional content extraction. Returns results with their contents.

bash

undefined

支持可选内容提取的语义搜索。返回包含内容的结果。

bash

undefined

Basic search

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "latest developments in AI agents", "numResults": 10 }' | jq '.results[] | {title, url, publishedDate}'

Search with content extraction

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "best practices for RAG systems", "numResults": 5, "contents": { "text": true, "highlights": { "numSentences": 3, "highlightsPerUrl": 2 }, "summary": {} } }' | jq '.results[] | {title, url, summary, highlights}'

Search with date filters and domain restrictions

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "OpenAI announcements", "numResults": 10, "startPublishedDate": "2024-01-01T00:00:00.000Z", "includeDomains": ["openai.com", "techcrunch.com", "theverge.com"], "contents": { "text": {"maxCharacters": 1000}, "summary": {} } }' | jq

Search with category filter

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "transformer architecture papers", "numResults": 10, "category": "research paper", "contents": { "text": true, "summary": {} } }' | jq

Deep search for comprehensive results

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "climate change mitigation strategies", "type": "deep", "numResults": 20, "contents": { "text": true, "summary": {} } }' | jq


**Search types:**
- `auto` (default): Intelligently combines neural and other methods
- `neural`: Pure semantic/embeddings-based search
- `fast`: Quick keyword-based search
- `deep`: Comprehensive search with query expansion

**Categories:** `company`, `research paper`, `news`, `pdf`, `github`, `tweet`, `personal site`, `financial report`, `people`

curl -s -X POST "https://api.exa.ai/search"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "climate change mitigation strategies", "type": "deep", "numResults": 20, "contents": { "text": true, "summary": {} } }' | jq


**搜索类型：**
- `auto`（默认）：智能结合神经搜索与其他方法
- `neural`：纯语义/基于嵌入的搜索
- `fast`：快速关键词搜索
- `deep`：带查询扩展的全面搜索

**分类：** `company`, `research paper`, `news`, `pdf`, `github`, `tweet`, `personal site`, `financial report`, `people`

2. Contents (

/contents

)

2. 内容提取（

/contents

）

Extract content from specific URLs.

bash

undefined

从特定URL提取内容。

bash

undefined

Get content from URLs

curl -s -X POST "https://api.exa.ai/contents"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "urls": [ "https://arxiv.org/abs/2307.06435", "https://example.com/article" ], "text": true, "summary": {}, "highlights": { "numSentences": 2, "highlightsPerUrl": 3 } }' | jq '.results[] | {url, title, summary, highlights}'

Get content with livecrawl for fresh data

curl -s -X POST "https://api.exa.ai/contents"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "urls": ["https://example.com/news"], "text": {"maxCharacters": 5000}, "livecrawl": "preferred" }' | jq


**Livecrawl options:**
- `never`: Only use cache
- `fallback`: Livecrawl when cache is empty (default)
- `preferred`: Try livecrawl first, fall back to cache
- `always`: Always livecrawl, never use cache

curl -s -X POST "https://api.exa.ai/contents"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "urls": ["https://example.com/news"], "text": {"maxCharacters": 5000}, "livecrawl": "preferred" }' | jq


**实时爬取选项：**
- `never`：仅使用缓存
- `fallback`：缓存为空时进行实时爬取（默认）
- `preferred`：优先尝试实时爬取，缓存作为备选
- `always`：始终进行实时爬取，从不使用缓存

3. Answer (

/answer

)

3. 直接答案（

/answer

）

Get direct answers to questions, grounded in web search results.

bash

undefined

基于网页搜索结果，获取问题的直接答案。

bash

undefined

Get a direct answer

curl -s -X POST "https://api.exa.ai/answer"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "What is the current population of Tokyo?" }' | jq '{answer, citations: [.citations[] | {title, url}]}'

Answer with full source text

curl -s -X POST "https://api.exa.ai/answer"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "What are the main features of GPT-4?", "text": true }' | jq

undefined

curl -s -X POST "https://api.exa.ai/answer"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "query": "What are the main features of GPT-4?", "text": true }' | jq

undefined

4. Research (

/research/v1

)

4. 深度研究（

/research/v1

）

Long-running research tasks with structured output. This is asynchronous - you create a task and poll for results.

bash

undefined

带结构化输出的长期研究任务。此为异步任务——你需要创建任务并轮询获取结果。

bash

undefined

Create a research task with structured output

RESEARCH_RESPONSE=$(curl -s -X POST "https://api.exa.ai/research/v1"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "exa-research", "instructions": "Compare the top 3 cloud providers (AWS, Azure, GCP) on pricing for compute instances. Return structured data.", "outputSchema": { "type": "object", "required": ["providers"], "properties": { "providers": { "type": "array", "items": { "type": "object", "required": ["name", "computePricing", "strengths"], "properties": { "name": {"type": "string"}, "computePricing": {"type": "string"}, "strengths": {"type": "array", "items": {"type": "string"}} } } } } } }')

RESEARCH_ID=$(echo "$RESEARCH_RESPONSE" | jq -r '.researchId') echo "Research ID: $RESEARCH_ID"

RESEARCH_RESPONSE=$(curl -s -X POST "https://api.exa.ai/research/v1"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "exa-research", "instructions": "Compare the top 3 cloud providers (AWS, Azure, GCP) on pricing for compute instances. Return structured data.", "outputSchema": { "type": "object", "required": ["providers"], "properties": { "providers": { "type": "array", "items": { "type": "object", "required": ["name", "computePricing", "strengths"], "properties": { "name": {"type": "string"}, "computePricing": {"type": "string"}, "strengths": {"type": "array", "items": {"type": "string"}} } } } } } }')

RESEARCH_ID=$(echo "$RESEARCH_RESPONSE" | jq -r '.researchId') echo "Research ID: $RESEARCH_ID"

Poll for results (repeat until status is "completed" or "failed")

curl -s "https://api.exa.ai/research/v1/$RESEARCH_ID"
-H "x-api-key: $EXA_API_KEY" | jq '{status, output}'

Simple research without schema (returns markdown report)

curl -s -X POST "https://api.exa.ai/research/v1"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "exa-research", "instructions": "Summarize the latest developments in quantum computing from the past 6 months." }' | jq


**Research models:**
- `exa-research` (default): Balanced speed and quality, adapts to task difficulty
- `exa-research-pro`: Maximum quality, more thorough analysis (slower)

**Best practices for research:**
- Be explicit about what information you want
- Describe how the agent should find information
- Specify the desired output format
- Keep schemas small (1-5 root fields)
- Use enums in schemas for better accuracy

curl -s -X POST "https://api.exa.ai/research/v1"
-H "x-api-key: $EXA_API_KEY"
-H "Content-Type: application/json"
-d '{ "model": "exa-research", "instructions": "Summarize the latest developments in quantum computing from the past 6 months." }' | jq


**研究模型：**
- `exa-research`（默认）：速度与质量平衡，可适应任务难度
- `exa-research-pro`：最高质量，分析更全面（速度较慢）

**研究最佳实践：**
- 明确说明你需要的信息
- 描述Agent应如何查找信息
- 指定期望的输出格式
- 保持Schema简洁（1-5个根字段）
- 在Schema中使用枚举以提高准确性

API Reference

API参考

Search Parameters

搜索参数

Parameter	Type	Description
`query`	string	The search query (required)
`numResults`	integer	Number of results (max 100, default 10)
`type`	string	Search type: `auto` , `neural` , `fast` , `deep`
`category`	string	Filter by content type
`includeDomains`	array	Only include results from these domains
`excludeDomains`	array	Exclude results from these domains
`startPublishedDate`	string	Only results published after (ISO 8601)
`endPublishedDate`	string	Only results published before (ISO 8601)
`includeText`	array	Must contain this text (max 1 string, 5 words)
`excludeText`	array	Must not contain this text
`contents`	object	Content extraction options

参数	类型	描述
`query`	string	搜索查询（必填）
`numResults`	integer	结果数量（最大100，默认10）
`type`	string	搜索类型： `auto` , `neural` , `fast` , `deep`
`category`	string	按内容类型过滤
`includeDomains`	array	仅包含来自这些域名的结果
`excludeDomains`	array	排除来自这些域名的结果
`startPublishedDate`	string	仅包含此日期之后发布的结果（ISO 8601格式）
`endPublishedDate`	string	仅包含此日期之前发布的结果（ISO 8601格式）
`includeText`	array	必须包含此文本（最多1个字符串，5个单词）
`excludeText`	array	必须不包含此文本
`contents`	object	内容提取选项

Contents Options

内容提取选项

Parameter	Type	Description
`text`	boolean/object	Extract full page text
`highlights`	object	Extract relevant snippets
`summary`	object	Generate page summary
`livecrawl`	string	Crawl freshness: `never` , `fallback` , `preferred` , `always`

参数	类型	描述
`text`	boolean/object	提取完整页面文本
`highlights`	object	提取相关片段
`summary`	object	生成页面摘要
`livecrawl`	string	爬取新鲜度： `never` , `fallback` , `preferred` , `always`

Response Fields

响应字段

Field	Description
`requestId`	Unique request identifier
`results`	Array of search results
`results[].id`	Document ID (use with /contents)
`results[].url`	Page URL
`results[].title`	Page title
`results[].publishedDate`	Publication date
`results[].author`	Author if available
`results[].text`	Full page content (if requested)
`results[].highlights`	Relevant snippets (if requested)
`results[].summary`	Page summary (if requested)
`costDollars`	Request cost breakdown

字段	描述
`requestId`	唯一请求标识符
`results`	搜索结果数组
`results[].id`	文档ID（与 `/contents` 配合使用）
`results[].url`	页面URL
`results[].title`	页面标题
`results[].publishedDate`	发布日期
`results[].author`	作者（若有）
`results[].text`	完整页面内容（若请求）
`results[].highlights`	相关片段（若请求）
`results[].summary`	页面摘要（若请求）
`costDollars`	请求费用明细

Pricing Notes

定价说明

Search: $0.005 per request (1-25 results), $0.025 (26-100 results)
Deep Search: $0.015 per request (1-25 results), $0.075 (26-100 results)
Contents: $0.001 per page for text/highlights/summary
Answer: Variable based on search and LLM usage
Research: Variable usage-based (searches + pages read + reasoning tokens)

搜索： 每次请求0.005美元（1-25条结果），0.025美元（26-100条结果）
深度搜索： 每次请求0.015美元（1-25条结果），0.075美元（26-100条结果）
内容提取： 每页0.001美元（文本/片段/摘要）
直接答案： 费用基于搜索和LLM使用量而定
深度研究： 基于使用量计费（搜索次数+读取页面数+推理令牌数）

exa-search

Original

Translation

Exa Web Search

Exa 网页搜索

Configuration

配置

Getting an API key

获取API密钥

Troubleshooting config

配置故障排除

Check config exists and is valid JSON

Check config exists and is valid JSON

Test connection

Test connection

Endpoint Selection Guide

端点选择指南

API Examples

API示例

Load API key

加载API密钥

1. Search (/search)

1. 搜索（/search）

Basic search

Basic search

Search with content extraction

Search with content extraction

Search with date filters and domain restrictions

Search with date filters and domain restrictions

Search with category filter

Search with category filter

Deep search for comprehensive results

Deep search for comprehensive results

2. Contents (/contents)

2. 内容提取（/contents）

Get content from URLs

Get content from URLs

Get content with livecrawl for fresh data

Get content with livecrawl for fresh data

3. Answer (/answer)

3. 直接答案（/answer）

Get a direct answer

Get a direct answer

Answer with full source text

Answer with full source text

4. Research (/research/v1)

4. 深度研究（/research/v1）

Create a research task with structured output

Create a research task with structured output

Poll for results (repeat until status is "completed" or "failed")

Poll for results (repeat until status is "completed" or "failed")

Simple research without schema (returns markdown report)

Simple research without schema (returns markdown report)

API Reference

API参考

Search Parameters

搜索参数

Contents Options

内容提取选项

Response Fields

响应字段

Pricing Notes

定价说明

1. Search (
`/search`
)

1. 搜索（
`/search`
）

2. Contents (
`/contents`
)

2. 内容提取（
`/contents`
）

3. Answer (
`/answer`
)

3. 直接答案（
`/answer`
）

4. Research (
`/research/v1`
)

4. 深度研究（
`/research/v1`
）