exa-search

Exa Search

API キーが必要です：https://dashboard.exa.ai/api-keys で取得してください

ヘッダー：x-api-key: $EXA_API_KEY

セマンティックなウェブ検索、結果のランキング、必要に応じた結果ごとの抽出を、1 回の生 HTTP 呼び出しで行うには、POST https://api.exa.ai/search を使用します。一般的な検索では、まず type: "auto" を指定してください。呼び出し元がページ本文、ハイライト、要約、鮮度を指定したクロール、サブページ、抽出したリンクを必要とする場合にのみ、contents を追加してください。

クイックスタート（cURL）

基本的な検索

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
  }'

ハイライト付きの検索

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
    }
  }'

フィルターと鮮度指定を使用

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
    }
  }'

詳細検索

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
  }'

エンドポイント

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

認証：x-api-key: <API_KEY> ヘッダーを使用します。Exa は Authorization: Bearer <API_KEY> も受け付けますが、一貫性を保つため、cURL の例では x-api-key を優先してください。

エージェントが検索結果を必要とする場合は、このエンドポイントを使用してください。エージェントがすでに URL を把握しており、抽出のみが必要な場合は、代わりに POST /contents を使用してください。

パラメーター

リクエストの主要パラメーター

パラメーター	型	必須	デフォルト	説明
query	string	はい	-	自然言語による検索クエリです。長く、意味的に豊かな説明が効果的です。
type	string	いいえ	auto	検索方式です：auto、fast、instant、deep-lite、deep、deep-reasoning のいずれかです。
numResults	integer	いいえ	10	返す結果の数です。エージェントのループでは小さな値を使用してください。最大値は 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	いいえ	-	US や GB などの 2 文字の ISO 国コードです。
moderation	boolean	いいえ	false	結果から安全でないコンテンツを除外します。
additionalQueries	string[]	いいえ	-	詳細検索のバリエーションに使用する追加のクエリです。メインの query と併用してください。
systemPrompt	string	いいえ	-	情報源の優先設定など、合成出力と詳細検索の計画に関する指示です。
outputSchema	object	いいえ	-	output.content を制御する JSON Schema です。合成出力と根拠情報が追加されます。
stream	boolean	いいえ	false	true の場合、単一の JSON レスポンスの代わりに SSE を返します。
compliance	string	いいえ	-	アカウントで有効になっている場合の、hipaa などのエンタープライズ専用コンプライアンスモードです。

contents の下にネストされたコンテンツパラメーター

/search では、text、highlights、summary を contents の下にネストする必要があります。

パラメーター	型	必須	デフォルト	説明
contents.text	boolean または object	いいえ	-	ページ全体のテキストを Markdown 形式で返します。オブジェクト形式では、maxCharacters、includeHtmlTags、verbosity、includeSections、excludeSections を指定できます。
contents.highlights	boolean または object	いいえ	-	クエリに関連する抜粋を返します。固定の文字数上限が必要な場合を除き、エージェントのワークフローでは 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 オブジェクトのオプション

パラメーター	型	デフォルト	説明
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 オブジェクトのオプション

デフォルトでは、最高品質の結果を得るために contents.highlights: true を推奨します。オブジェクト形式は、エージェントが独自の焦点や文字数上限を必要とする場合にのみ使用してください。

パラメーター	型	デフォルト	説明
query	string	-	返す抜粋を決めるためのカスタムクエリです。
maxCharacters	integer	-	URL ごとのハイライト文字数の上限です。呼び出し元に厳密な上限がある場合を除き、省略してください。

Summary オブジェクトのオプション

パラメーター	型	デフォルト	説明
query	string	-	要約用のカスタムクエリです。
schema	object	-	結果ごとの構造化された要約を定義する JSON Schema です。

検索タイプ

検索のtypeは、取得と合成のモードを制御します。出力形式だけでなく、ワークフローに適したモードを選んでください。outputSchemaはすべての検索タイプで使用できます。検索プロセス自体に、より多くの計画、合成、または推論が必要な場合は、より深いモードを使用してください。

タイプ	最適な用途	トレードオフ
auto	一般的なデフォルト検索と、ほとんどの新しい統合	呼び出し側が取得戦略を調整する必要なく、速度と品質のバランスを取ります。
fast	低遅延のエージェントループや製品の処理経路	autoより高速です。最大限の推論の深さより応答性が重要な場合に使用してください。
instant	リアルタイムUI、チャット、音声、自動補完形式の処理経路	最も低遅延の処理経路です。深い合成ではなく、素早い取得に使用してください。
deep-lite	軽量な調査や合成	autoより計画と合成を強化しつつ、完全なdeepより軽量です。
deep	複数ステップの調査、比較、合成を多く含む取得	遅延は大きくなります。複数の情報源にわたる探索が必要なクエリに適しています。
deep-reasoning	曖昧さが大きい、または複雑なトレードオフを伴う難しい調査タスク	最も遅延が大きく、推論の深さも最大です。

遅延や推論の深さが主な制約でない限り、autoを使用してください。時間的制約のある呼び出しには、fastまたはinstantを使用してください。クエリで複数ステップにわたる情報源の発見、比較、または合成が必要な場合は、deep、deep-lite、またはdeep-reasoningを使用してください。

モードのみの例

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

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

構造化出力

動作にはsystemPromptを、形式にはoutputSchemaを使用してください。スキーマは簡潔に保ちます。名前付きフィールドは数個にとどめ、ネストは浅くし、配列にはitemsを指定してください。以下の例は、/searchで扱えるおおよその最大幅です。列を増やす必要がある場合は、スキーマを拡張するのではなく、重要度の低い列を削除してください。

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
    }
  }'

スキーマは簡潔で、範囲を限定したものにしてください。スキーマに引用フィールドを追加しないでください。根拠情報はoutput.groundingで別途返されます。

ストリーミング

ストリーミングは合成された出力に適用されるため、outputSchemaを-N、Accept: text/event-stream、およびstream: trueとともに指定してください。outputSchemaがない場合、streamがtrueでも、エンドポイントは通常のJSON検索レスポンスを返します。

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
    }
  }'

ストリーミングはJSONではなくSSEとして扱ってください。各data:フレームにはOpenAI互換のチャット補完チャンクが含まれます。choices[0].delta.contentから部分テキストを読み取り、完了フレームやエラーフレームも確実に処理してください。

レスポンスフィールド

フィールド	型	説明
requestId	string	一意のリクエスト識別子です。
results	array	順位付けされた結果オブジェクトです。
results[].title	string	ページタイトルです。
results[].url	string	ページURLです。
results[].publishedDate	string or null	利用可能な場合の推定公開日です。
results[].author	string or 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 or object	outputSchemaが指定された場合の合成出力です。
output.grounding	array	合成されたフィールドの引用と信頼度ラベルです。
costDollars.total	number	返される場合のリクエスト総費用です。
searchTime	number	返される場合の検索遅延です。

重大な注意点

• /search では、contents 内に text、highlights、summary を含めてください。
• トップレベルに text、highlights、summary を指定しないでください。この形式は /contents 用です。
• tokensNum は指定しないでください。抽出テキストの上限には contents.text.maxCharacters を使用してください。
• 新しいリクエストでは useAutoprompt、numSentences、highlightsPerUrl を使用しないでください。
• livecrawl の代わりに contents.maxAgeHours を使用してください。
• ドキュメントに記載されているカテゴリのみを使用してください：company、people、research paper、news、personal site、financial report。
• 無効なカテゴリとフィルターの組み合わせは避けてください。company と people は startPublishedDate または endPublishedDate をサポートしていません。company は excludeDomains をサポートしていますが、people はサポートしていません。また、people の includeDomains で指定できるのは LinkedIn のドメインのみです。
• デフォルトでは、contents.highlights、contents.text、contents.summary のいずれか1つを選択してください。各ページの複数の形式が実際に必要な場合にのみ、複数のモードを組み合わせてください。
• stream: true と outputSchema を組み合わせた場合にのみ SSE が返されます。それ以外の場合、/search は通常の JSON レスポンスを返します。