discover-api

Bright Data — Discover API

Discover は意図に基づいて順位付けされるセマンティック Web 検索です。query と intent を指定すると、AI による関連性スコア付きの結果が返されます。必要に応じて、解析済みページの全コンテンツも取得できます。生のキーワード順位よりも結果の品質・関連性が重要な場合に適した基本機能であり、検索拡張生成（RAG）、調査、ナレッジベースのパイプラインを構築するための基盤です。

Discover と関連機能の使い分け：

• キーワードで「X で何が上位表示されるか」を調べる SERP → search スキル（bdata search）を使用します。
• 既知のプラットフォーム（Amazon／LinkedIn／…）から構造化データを取得する → data-feeds を使用します。
• Discover を使った調査概要全体、または RAG／検索パイプライン → live-research または rag-pipeline を使用します（どちらもこの API を呼び出します）。

仕組み（非同期：開始 → ポーリング）

1. ジョブを開始すると、task_id が返されます。
2. status が "done" になるまで、task_id を使ってポーリングします（処理中は "processing"）。
3. results[] を読み取ります。

CLI と SDK では開始とポーリングが自動的に行われます。ラッパーでは公開されていないパラメーター（特に mode）が必要な場合に備えて、生の REST フローを以下に示します。

利用方法を選ぶ

対象	使用する方法
ターミナルで単発またはスクリプトから実行する	CLI：bdata discover
Node／TS コードを記述する	JS SDK：client.discover() — js-sdk-best-practices を参照
Python コードを記述する	Python SDK：client.discover() — python-sdk-best-practices を参照
mode（deep／fast／zeroRanking）または include_images が必要	Raw REST（現時点ではラッパーからは利用できません）

CLI — bdata discover

まずセットアップゲートを通過します：

command -v bdata >/dev/null 2>&1 || echo "CLI missing — see bright-data-best-practices/references/cli-setup.md"
bdata zones >/dev/null 2>&1 || echo "not authenticated — run: bdata login"

# Intent-ranked discovery, JSON
bdata discover "enterprise LLM platforms" \
  --intent "vendor pages with pricing" \
  --num-results 15 --json --pretty

# With parsed page content in one pass (for RAG / research)
bdata discover "webhook retry best practices" \
  --include-content --num-results 10 -o results.json

# Date-bounded
bdata discover "react server components" \
  --start-date 2025-01-01 --end-date 2025-12-31 --num-results 20 --json

結果は .results[] に格納されます。各結果には title、link、description、 relevance_score が含まれ、--include-content を指定すると content も含まれます。CLI のフラグ一覧： search スキル → references/flags.md。

SDK（それぞれ 1 行）

// JS — see js-sdk-best-practices for all options.
// VERIFIED v1.1.0: discover() returns a WRAPPER { success, data:[...], totalResults, cost, taskId, ... }
const res = await client.discover('Tesla battery tech', { intent: 'EV battery breakthroughs', numResults: 10, includeContent: true });
const rows = res.data;   // ← rows are in .data (NOT a bare array, NOT .results)

# Python — see python-sdk-best-practices (confirm whether rows come back directly, under .data, or .results)
out = client.discover(query="Tesla battery tech", intent="EV battery breakthroughs")

Raw REST（mode を含む完全な制御）

# 1) Trigger
task_id=$(curl -s -X POST https://api.brightdata.com/discover \
  -H "Authorization: Bearer $BRIGHTDATA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"post-quantum cryptography adoption","intent":"enterprise migration guides","mode":"deep","num_results":20,"include_content":true}' \
  | jq -r '.task_id')

# 2) Poll until done
while :; do
  resp=$(curl -s "https://api.brightdata.com/discover?task_id=$task_id" -H "Authorization: Bearer $BRIGHTDATA_API_TOKEN")
  [ "$(echo "$resp" | jq -r '.status')" = "done" ] && break
  sleep 3
done
echo "$resp" | jq '.results'

パラメーター（REST ボディ — 網羅的な正式仕様）

query は必須で、それ以外はすべて任意です。CLI／SDK で公開されているのは一部です（サーフェスごとの正確な対応表は references/api-reference.md を参照してください）。

Param	Type	Default	Notes
query	string	—	必須、最大 1500 文字
intent	string	—	目標の説明、最大 3000 文字。強く推奨 — 順位付けを左右します
mode	enum	standard	standard | zeroRanking | deep | fast（REST のみ）
num_results	int	—	1～20。zeroRanking では無視されます
filter_keywords	string[]	—	結果に必ず含める完全一致キーワード
include_content	bool	false	解析済みのページ／PDF コンテンツ（PDF は最大 50 MB、30 秒）。zeroRanking ではサポートされません
include_images	bool	false	画像配列（REST のみ）
format	enum	json	json | md（SDK が受け付けるのは json のみ）
country	string	US	2 文字の ISO コード
city	string	—	SERP の都市ターゲティング
language	string	en	31 言語
start_date / end_date	string	—	YYYY-MM-DD（REST のみ）
remove_duplicates	bool	true	結果の重複を除去（REST のみ）

モード（目的に応じて選択）

Mode	What it does	Use for
standard (デフォルト)	バランスの取れた検索の深さと AI による順位付け	一般的な意図に基づく検索
deep	網羅的で、より広範囲を検索します。低速です	live-research、トピックを包括的に網羅する場合
fast	低レイテンシ向けに最適化されています	時間的制約のある用途／対話型の用途
zeroRanking	AI による順位付けを行わず、生の結果を最大量取得します。num_results を無視し、include_content は利用できません	rag-pipeline 用のコーパスを一括収集する場合

mode は現在 REST のみで利用できます。CLI と SDK では公開されていません。CLI／SDK で deep モードに近い結果を得るには、num_results を大きくし、明確な intent を指定します。真の deep／zeroRanking を使うには、上記の生の REST フローを使用してください。

結果の形式

REST + CLI（検証済み）— 行は results の下に格納されます：

{
  "status": "done",
  "duration_seconds": 12.4,
  "timestamp": "2026-06-08T08:36:55.709Z",
  "results": [
    { "link": "https://…", "title": "…", "description": "…",
      "relevance_score": 0.87, "content": "…(when --include-content)…" }
  ]
}

JS SDK（v1.1.0 で検証済み）— 行はラッパー内の data の下に格納されます：

{ success: true, data: [ {link, title, description, relevance_score, content?} ],
  totalResults, cost, taskId, query, intent, durationSeconds, triggerSentAt, dataFetchedAt }

⚠️ サーフェス間の注意点： REST/CLI では行が .results の下に返されますが、JS SDK では .data の下に返されます（すべてが {success, ...} でラップされるため、data を読み取る前に success を確認してください）。サーフェス間で同じ形式だと思い込まないでください。

relevance_score は浮動小数点数（snake_case）です。値が高いほど intent との関連性が高くなります。 content はデフォルトでプレーンテキストです（REST の format=md では Markdown）。relevance_score が高くても、コンテンツの質が高いとは限りません。ページが 404 のスタブやナビゲーションのみの場合もあります。使用前に、コンテンツの長さと「not found」／ブロックページの特徴を確認してください。

検証ゲート

1. トリガーから task_id が返された（REST：status:"ok"）。ID がない場合は、認証情報、またはアカウントで Discover が有効になっているかを確認してください（無効の場合は 403）。
2. 読み取る前に status:"done" までポーリングした— processing 中に results を読み取らないでください。
3. results[] が空ではない— 空の場合、クエリ／intent が狭すぎます。条件を緩めて再試行してください。空の結果で成功を主張しないでください。
4. include_content の本文がブロックページではない— content 内で captcha、Just a moment、Access Denied、cf-browser-verification を検索してください（scrape と同じリストです）。問題のある行は除外してください。
5. 関連性の妥当性確認— 上位の relevance_score が低い、またはトピックから外れている場合は、query だけでなく intent を明確にしてください。

注意事項

• intent を指定せず、query だけを渡すこと — intent によるランキングの利点をすべて失います。必ず intent を指定してください。
• Discover をキーワード SERP として扱うこと — 「X で何が上位表示されるか」を調べるには、search を使用してください。
• num_results を 20 より大きく設定すること — 上限は 20 です。さらに必要な場合は、複数の対象を絞ったクエリを実行して重複を除去してください（live-research を参照）。
• zeroRanking を使用してから、include_content や num_results が適用されると期待すること — 適用されません。
• status:"done" より前に結果を読み取ること。
• 一時的な success:false（SDK）／空の results（REST/CLI）を致命的なエラーとして扱うこと — 一時的な問題であることが多いため、まずバックオフを入れて一度再試行してください（references/api-reference.md → 一時的な失敗を参照）。
• 呼び出しが失敗したときに relevance_score や content を捏造すること — 代わりに失敗を報告してください。

参考資料

• references/api-reference.md — REST エンドポイントの完全な仕様、サーフェスごとの正確なパラメータ一覧（REST、CLI、JS SDK、Python SDK）、エラーコード、制限事項。

関連スキル

• live-research — 複数クエリでの Discover → 重複除去 → 引用付きの要約を作成します。
• rag-pipeline — Discover（include_content）→ チャンク化 → 埋め込み → 検索。
• search — intent によるランキングが不要な場合のキーワード SERP（bdata search）。
• js-sdk-best-practices / python-sdk-best-practices — client.discover() のオプションの詳細。