exa-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Exa Search

Requires API key: Get one at https://dashboard.exa.ai/api-keys
Header:
x-api-key: $EXA_API_KEY

Use

POST https://api.exa.ai/search

for semantic web retrieval, ranked results, and optional result-level extraction in one raw HTTP call. Start with

type: "auto"

for general retrieval. Add

contents

only when the caller needs page text, highlights, summaries, freshness-controlled crawling, subpages, or extracted links.

需要API密钥：前往https://dashboard.exa.ai/api-keys获取
请求头：
x-api-key: $EXA_API_KEY

使用

POST https://api.exa.ai/search

通过一次原生HTTP调用实现语义网页检索、结果排序以及可选的结果级提取。通用检索请从

type: "auto"

开始。仅当调用方需要页面文本、高亮内容、摘要、时效性控制爬取、子页面或提取链接时，才添加

contents

参数。

Quick Start (cURL)

快速开始（cURL）

Basic search

基础搜索

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 10
  }'

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 10
  }'

Search with highlights

带高亮的搜索

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 5,
    "contents": {
      "highlights": true
    }
  }'

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "numResults": 5,
    "contents": {
      "highlights": true
    }
  }'

With filters and freshness

带筛选和时效性控制的搜索

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "AI regulation policy updates",
    "type": "auto",
    "category": "news",
    "numResults": 10,
    "includeDomains": ["reuters.com", "bbc.com"],
    "startPublishedDate": "2025-01-01",
    "contents": {
      "text": {
        "maxCharacters": 2000
      },
      "maxAgeHours": 24,
      "livecrawlTimeout": 12000
    }
  }'

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "AI regulation policy updates",
    "type": "auto",
    "category": "news",
    "numResults": 10,
    "includeDomains": ["reuters.com", "bbc.com"],
    "startPublishedDate": "2025-01-01",
    "contents": {
      "text": {
        "maxCharacters": 2000
      },
      "maxAgeHours": 24,
      "livecrawlTimeout": 12000
    }
  }'

Deep search

深度搜索

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "map the major technical and commercial tradeoffs in sodium-ion batteries for grid storage",
    "type": "deep",
    "numResults": 8
  }'

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "map the major technical and commercial tradeoffs in sodium-ion batteries for grid storage",
    "type": "deep",
    "numResults": 8
  }'

Endpoint

接口地址

text

POST https://api.exa.ai/search

Authentication:

x-api-key: <API_KEY>

header. Exa also accepts

Authorization: Bearer <API_KEY>

, but prefer

x-api-key

in cURL examples for consistency.

Use this endpoint when the agent needs search results. If the agent already has URLs and only needs extraction, use

POST /contents

instead.

text

POST https://api.exa.ai/search

认证方式：通过请求头

x-api-key: <API_KEY>

。Exa也支持

Authorization: Bearer <API_KEY>

，但为保持一致性，cURL示例中优先使用

x-api-key

。

当Agent需要搜索结果时使用此接口。若Agent已拥有URL且仅需要提取内容，请使用

POST /contents

接口。

Parameters

参数说明

Core request parameters

核心请求参数

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	Natural-language search query. Long, semantically rich descriptions work well.
`type`	string	No	`auto`	Search method: `auto` , `fast` , `instant` , `deep-lite` , `deep` , or `deep-reasoning` .
`numResults`	integer	No	`10`	Number of results to return. Use small values for agent loops; maximum is 100.
`category`	string	No	-	Specialized result type: `company` , `people` , `research paper` , `news` , `personal site` , or `financial report` .
`includeDomains`	string[]	No	-	Only return results from these domains, paths, or wildcard patterns. Max 1200.
`excludeDomains`	string[]	No	-	Exclude these domains, paths, or wildcard patterns. Max 1200.
`startPublishedDate`	string	No	-	ISO 8601 lower bound for result publication date.
`endPublishedDate`	string	No	-	ISO 8601 upper bound for result publication date.
`userLocation`	string	No	-	Two-letter ISO country code such as `US` or `GB` .
`moderation`	boolean	No	`false`	Filter unsafe content from results.
`additionalQueries`	string[]	No	-	Extra query variants for deep-search variants. Use alongside the main `query` .
`systemPrompt`	string	No	-	Instructions for synthesized output and deep-search planning, such as source preferences.
`outputSchema`	object	No	-	JSON Schema controlling `output.content` . Adds synthesized output and grounding.
`stream`	boolean	No	`false`	If `true` , returns SSE instead of a single JSON response.
`compliance`	string	No	-	Enterprise-only compliance mode, such as `hipaa` , when enabled for the account.

参数	类型	是否必填	默认值	描述
`query`	string	是	-	自然语言搜索查询。使用语义丰富的长描述效果更佳。
`type`	string	否	`auto`	搜索方式： `auto` 、 `fast` 、 `instant` 、 `deep-lite` 、 `deep` 或 `deep-reasoning` 。
`numResults`	integer	否	`10`	返回结果数量。Agent循环中使用较小值；最大值为100。
`category`	string	否	-	特定结果类型： `company` 、 `people` 、 `research paper` 、 `news` 、 `personal site` 或 `financial report` 。
`includeDomains`	string[]	否	-	仅返回来自这些域名、路径或通配符模式的结果。最多支持1200个。
`excludeDomains`	string[]	否	-	排除来自这些域名、路径或通配符模式的结果。最多支持1200个。
`startPublishedDate`	string	否	-	结果发布日期的ISO 8601格式下限。
`endPublishedDate`	string	否	-	结果发布日期的ISO 8601格式上限。
`userLocation`	string	否	-	两位ISO国家代码，例如 `US` 或 `GB` 。
`moderation`	boolean	否	`false`	过滤结果中的不安全内容。
`additionalQueries`	string[]	否	-	深度搜索变体的额外查询变体。需与主 `query` 配合使用。
`systemPrompt`	string	否	-	用于合成输出和深度搜索规划的指令，例如来源偏好。
`outputSchema`	object	否	-	控制 `output.content` 的JSON Schema。添加合成输出和溯源信息。
`stream`	boolean	否	`false`	若为 `true` ，则返回SSE而非单个JSON响应。
`compliance`	string	否	-	企业专属合规模式，例如 `hipaa` （仅当账户启用时可用）。

Content parameters nested under

contents

contents

下的嵌套内容参数

/search

text

highlights

, and

summary

must be nested under

contents

Parameter	Type	Required	Default	Description
`contents.text`	boolean or object	No	-	Return full page text as markdown. Object form supports `maxCharacters` , `includeHtmlTags` , `verbosity` , `includeSections` , and `excludeSections` .
`contents.highlights`	boolean or object	No	-	Return query-relevant excerpts. Prefer `true` for agent workflows unless a fixed character budget is required.
`contents.summary`	boolean or object	No	-	Return per-result LLM summaries. Use sparingly because each result adds synthesis work.
`contents.maxAgeHours`	integer	No	-	Freshness control. `0` always live crawls; `-1` uses cache only; omit for default cache-first behavior with crawl fallback.
`contents.livecrawlTimeout`	integer	No	`10000`	Timeout for live crawling in milliseconds. Use `10000` to `15000` for most freshness-sensitive calls.
`contents.subpages`	integer	No	`0`	Number of linked subpages to crawl per result.
`contents.subpageTarget`	string or string[]	No	-	Terms used to prioritize which subpages matter, such as `["api", "pricing"]` .
`contents.extras.links`	integer	No	`0`	Number of links to extract from each result page.
`contents.extras.imageLinks`	integer	No	`0`	Number of image URLs to extract from each result page.

在

/search

接口中，

text

、

highlights

和

summary

必须嵌套在

contents

下。

参数	类型	是否必填	默认值	描述
`contents.text`	boolean或object	否	-	返回完整页面文本（Markdown格式）。对象形式支持 `maxCharacters` 、 `includeHtmlTags` 、 `verbosity` 、 `includeSections` 和 `excludeSections` 。
`contents.highlights`	boolean或object	否	-	返回与查询相关的摘录。Agent工作流中优先使用 `true` ，除非需要固定字符预算。
`contents.summary`	boolean或object	否	-	返回每个结果的LLM摘要。需谨慎使用，因为每个结果都会增加合成工作量。
`contents.maxAgeHours`	integer	否	-	时效性控制。 `0` 表示始终实时爬取； `-1` 表示仅使用缓存；省略则使用默认的缓存优先、爬取回退策略。
`contents.livecrawlTimeout`	integer	否	`10000`	实时爬取的超时时间（毫秒）。对时效性敏感的调用建议使用 `10000` 至 `15000` 。
`contents.subpages`	integer	否	`0`	每个结果爬取的链接子页面数量。
`contents.subpageTarget`	string或string[]	否	-	用于优先选择重要子页面的关键词，例如 `["api", "pricing"]` 。
`contents.extras.links`	integer	否	`0`	从每个结果页面提取的链接数量。
`contents.extras.imageLinks`	integer	否	`0`	从每个结果页面提取的图片URL数量。

Text object options

Text对象选项

Parameter	Type	Default	Description
`maxCharacters`	integer	-	Character limit for returned text. Use this instead of `tokensNum` .
`includeHtmlTags`	boolean	`false`	Preserve HTML tags in output.
`verbosity`	string	`compact`	`compact` , `standard` , or `full` . Pair fresh section-aware extraction with `contents.maxAgeHours: 0` .
`includeSections`	string[]	-	Only include selected sections: `header` , `navigation` , `banner` , `body` , `sidebar` , `footer` , `metadata` .
`excludeSections`	string[]	-	Exclude selected sections from the same section list.

参数	类型	默认值	描述
`maxCharacters`	integer	-	返回文本的字符限制。请使用此参数替代 `tokensNum` 。
`includeHtmlTags`	boolean	`false`	在输出中保留HTML标签。
`verbosity`	string	`compact`	可选值： `compact` 、 `standard` 或 `full` 。与 `contents.maxAgeHours: 0` 配合使用可实现基于最新内容的分段提取。
`includeSections`	string[]	-	仅包含指定分段： `header` 、 `navigation` 、 `banner` 、 `body` 、 `sidebar` 、 `footer` 、 `metadata` 。
`excludeSections`	string[]	-	排除指定分段（可选范围同上）。

Highlights object options

Highlights对象选项

Prefer

contents.highlights: true

for the highest-quality default. Only use object form when the agent needs a custom focus or budget.

Parameter	Type	Default	Description
`query`	string	-	Custom query guiding which excerpts are returned.
`maxCharacters`	integer	-	Cap highlight characters per URL. Omit unless the caller has a strict budget.

优先使用

contents.highlights: true

以获得最佳默认效果。仅当Agent需要自定义焦点或预算时才使用对象形式。

参数	类型	默认值	描述
`query`	string	-	用于指导返回摘录的自定义查询。
`maxCharacters`	integer	-	每个URL的高亮内容字符上限。除非调用方有严格预算，否则无需设置。

Summary object options

Summary对象选项

Parameter	Type	Default	Description
`query`	string	-	Custom query for the summary.
`schema`	object	-	JSON Schema for structured per-result summaries.

参数	类型	默认值	描述
`query`	string	-	用于生成摘要的自定义查询。
`schema`	object	-	用于结构化单结果摘要的JSON Schema。

Search Types

搜索类型

type

controls the retrieval and synthesis mode. Pick the mode for the workflow, not just the output format.

outputSchema

can be used with any search type; use deeper modes when the search process itself needs more planning, synthesis, or reasoning.

Type	Best for	Tradeoff
`auto`	General default search and most new integrations	Balances speed and quality without requiring the caller to tune retrieval strategy.
`fast`	Low-latency agent loops and product paths	Faster than `auto` ; use when responsiveness matters more than maximum reasoning depth.
`instant`	Real-time UI, chat, voice, and autocomplete-style paths	Lowest latency path; use for quick retrieval rather than deep synthesis.
`deep-lite`	Lightweight research or synthesis	Adds more planning and synthesis than `auto` while staying lighter than full `deep` .
`deep`	Multi-step research, comparisons, and synthesis-heavy retrieval	Higher latency; better when the query needs exploration across several sources.
`deep-reasoning`	Hard research tasks with high ambiguity or complex tradeoffs	Highest latency and reasoning depth.

Use

auto

unless latency or reasoning depth is the primary constraint. Use

fast

instant

for time-sensitive calls. Use

deep

deep-lite

, or

deep-reasoning

when the query needs multi-step source discovery, comparison, or synthesis.

搜索

type

控制检索和合成模式。请根据工作流选择模式，而非仅根据输出格式。

outputSchema

可与任何搜索类型配合使用；当搜索过程本身需要更多规划、合成或推理时，使用更深度的模式。

类型	适用场景	权衡点
`auto`	通用默认搜索和大多数新集成	在速度和质量之间取得平衡，无需调用方调整检索策略。
`fast`	低延迟Agent循环和产品路径	比 `auto` 更快；当响应速度比最大推理深度更重要时使用。
`instant`	实时UI、聊天、语音和自动补全类场景	延迟最低的模式；用于快速检索而非深度合成。
`deep-lite`	轻量级研究或合成	比 `auto` 增加更多规划和合成，同时比完整 `deep` 模式更轻量化。
`deep`	多步骤研究、对比和重度合成检索	延迟较高；当查询需要跨多个来源探索时效果更佳。
`deep-reasoning`	高歧义或复杂权衡的疑难研究任务	延迟和推理深度最高。

除非延迟或推理深度是主要限制因素，否则请使用

auto

。对时间敏感的调用使用

fast

或

instant

。当查询需要多步骤来源发现、对比或合成时，使用

deep

、

deep-lite

或

deep-reasoning

。

Mode-only examples

仅指定模式的示例

json

{
  "query": "recent product launches from major AI chip companies",
  "type": "fast",
  "numResults": 5
}

json

{
  "query": "compare competing explanations for the recent rise in grid-scale battery deployments",
  "type": "deep",
  "numResults": 8
}

json

{
  "query": "recent product launches from major AI chip companies",
  "type": "fast",
  "numResults": 5
}

json

{
  "query": "compare competing explanations for the recent rise in grid-scale battery deployments",
  "type": "deep",
  "numResults": 8
}

Structured Output

结构化输出

Use

systemPrompt

for behavior and

outputSchema

for shape.

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "compare the latest frontier AI model releases",
    "type": "deep",
    "systemPrompt": "Prefer official sources and avoid duplicate results.",
    "outputSchema": {
      "type": "object",
      "properties": {
        "models": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "notable_claims": {
                "type": "array",
                "items": { "type": "string" }
              }
            },
            "required": ["name", "notable_claims"]
          }
        }
      },
      "required": ["models"]
    },
    "contents": {
      "highlights": true
    }
  }'

Keep schemas compact and bounded. Do not add citation fields to the schema; grounding is returned separately in

output.grounding

使用

systemPrompt

定义行为，

outputSchema

定义输出结构。

bash

curl -sS -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "compare the latest frontier AI model releases",
    "type": "deep",
    "systemPrompt": "Prefer official sources and avoid duplicate results.",
    "outputSchema": {
      "type": "object",
      "properties": {
        "models": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "notable_claims": {
                "type": "array",
                "items": { "type": "string" }
              }
            },
            "required": ["name", "notable_claims"]
          }
        }
      },
      "required": ["models"]
    },
    "contents": {
      "highlights": true
    }
  }'

请保持Schema简洁且有边界。不要在Schema中添加引用字段；溯源信息会单独返回在

output.grounding

中。

Streaming

流式输出

Streaming applies to synthesized output, so include

outputSchema

along with

-N

Accept: text/event-stream

, and

stream: true

. Without

outputSchema

, the endpoint returns the normal JSON search response even when

stream

true

bash

curl -sS -N -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "recent grid-scale battery deployments",
    "type": "deep",
    "stream": true,
    "outputSchema": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      },
      "required": ["summary"]
    },
    "contents": {
      "highlights": true
    }
  }'

Treat streaming as SSE rather than JSON. Each

data:

frame contains an OpenAI-compatible chat completion chunk; read partial text from

choices[0].delta.content

and handle completion or error frames defensively.

流式输出适用于合成输出，因此需同时包含

outputSchema

、

-N

、

Accept: text/event-stream

和

stream: true

。若未指定

outputSchema

，即使

stream

设为

true

，接口仍会返回常规JSON搜索响应。

bash

curl -sS -N -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "recent grid-scale battery deployments",
    "type": "deep",
    "stream": true,
    "outputSchema": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      },
      "required": ["summary"]
    },
    "contents": {
      "highlights": true
    }
  }'

请将流式输出视为SSE而非JSON。每个

data:

帧包含兼容OpenAI的聊天补全块；从

choices[0].delta.content

读取部分文本，并谨慎处理完成或错误帧。

Response Fields

响应字段

Field	Type	Description
`requestId`	string	Unique request identifier.
`results`	array	Ranked result objects.
`results[].title`	string	Page title.
`results[].url`	string	Page URL.
`results[].publishedDate`	string or null	Estimated publication date when available.
`results[].author`	string or null	Author when available.
`results[].text`	string	Returned when `contents.text` is requested.
`results[].highlights`	string[]	Returned when `contents.highlights` is requested.
`results[].highlightScores`	number[]	Similarity scores for highlights.
`results[].summary`	string	Returned when `contents.summary` is requested.
`results[].subpages`	array	Nested result objects from subpage crawling.
`results[].extras.links`	string[]	Extracted links when requested.
`output.content`	string or object	Synthesized output when `outputSchema` is provided.
`output.grounding`	array	Citations and confidence labels for synthesized fields.
`costDollars.total`	number	Total request cost when returned.
`searchTime`	number	Search latency when returned.

字段	类型	描述
`requestId`	string	唯一请求标识符。
`results`	array	排序后的结果对象数组。
`results[].title`	string	页面标题。
`results[].url`	string	页面URL。
`results[].publishedDate`	string或null	可用时返回估算的发布日期。
`results[].author`	string或null	可用时返回作者信息。
`results[].text`	string	当请求 `contents.text` 时返回。
`results[].highlights`	string[]	当请求 `contents.highlights` 时返回。
`results[].highlightScores`	number[]	高亮内容的相似度得分。
`results[].summary`	string	当请求 `contents.summary` 时返回。
`results[].subpages`	array	子页面爬取的嵌套结果对象数组。
`results[].extras.links`	string[]	请求时返回提取的链接。
`output.content`	string或object	当提供 `outputSchema` 时返回合成输出。
`output.grounding`	array	合成字段的引用和置信度标签。
`costDollars.total`	number	返回时显示请求总成本。
`searchTime`	number	返回时显示搜索延迟。

Critical Pitfalls

关键注意事项

Keep
```
text
```
,
```
highlights
```
, and
```
summary
```
inside
```
contents
```
on
```
/search
```
.
Do not send top-level
```
text
```
,
```
highlights
```
, or
```
summary
```
; that shape belongs to
```
/contents
```
.
Do not send
```
tokensNum
```
; use
```
contents.text.maxCharacters
```
to cap extracted text.

Do not use

useAutoprompt

numSentences

, or

highlightsPerUrl

in new requests.

Use
```
contents.maxAgeHours
```
instead of
```
livecrawl
```
.

Use documented categories only:

company

people

research paper

news

personal site

, and

financial report

Avoid invalid category/filter combinations.
```
company
```
and
```
people
```
do not support
```
startPublishedDate
```
or
```
endPublishedDate
```
.
```
company
```
supports
```
excludeDomains
```
;
```
people
```
does not, and
```
people
```
only accepts LinkedIn domains in
```
includeDomains
```
.
Pick one of
```
contents.highlights
```
,
```
contents.text
```
, or
```
contents.summary
```
by default. Stack modes only when the caller truly needs multiple views of each page.
Expect SSE only when
```
stream: true
```
is paired with
```
outputSchema
```
; otherwise
```
/search
```
returns its normal JSON response.

在
```
/search
```
接口中，需将
```
text
```
、
```
highlights
```
和
```
summary
```
放在
```
contents
```
内。
不要在顶层发送
```
text
```
、
```
highlights
```
或
```
summary
```
；该格式属于
```
/contents
```
接口。
不要发送
```
tokensNum
```
；请使用
```
contents.text.maxCharacters
```
限制提取文本的长度。

新请求中不要使用

useAutoprompt

、

numSentences

或

highlightsPerUrl

。

使用
```
contents.maxAgeHours
```
替代
```
livecrawl
```
。

仅使用文档中列出的类别：

company

、

people

、

research paper

、

news

、

personal site

和

financial report

。

避免无效的类别/筛选组合。
```
company
```
和
```
people
```
不支持
```
startPublishedDate
```
或
```
endPublishedDate
```
。
```
company
```
支持
```
excludeDomains
```
；
```
people
```
不支持，且
```
people
```
仅接受LinkedIn域名在
```
includeDomains
```
中。
默认情况下，请选择
```
contents.highlights
```
、
```
contents.text
```
或
```
contents.summary
```
中的一个。仅当调用方确实需要每个页面的多种视图时，才同时使用多种模式。
仅当
```
stream: true
```
与
```
outputSchema
```
配合使用时，才会返回SSE；否则
```
/search
```
接口返回常规JSON响应。

exa-search

Original

Translation

Exa Search

Exa Search

Quick Start (cURL)

快速开始（cURL）

Basic search

基础搜索

Search with highlights

带高亮的搜索

With filters and freshness

带筛选和时效性控制的搜索

Deep search

深度搜索

Endpoint

接口地址

Parameters

参数说明

Core request parameters

核心请求参数

Content parameters nested under contents

contents下的嵌套内容参数

Text object options

Text对象选项

Highlights object options

Highlights对象选项

Summary object options

Summary对象选项

Search Types

搜索类型

Mode-only examples

仅指定模式的示例

Structured Output

结构化输出

Streaming

流式输出

Response Fields

响应字段

Critical Pitfalls

关键注意事项

Content parameters nested under
`contents`

`contents`
下的嵌套内容参数