discover-api

Bright Data — Discover API

Discover 是按意图排序的语义网页搜索。你提供 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. 使用 task_id 轮询，直到 status 为 "done"（中间状态为 "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	原始 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（每种方式各一行）

// 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")

原始 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）。

参数	类型	默认值	说明
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）

模式（按目标选择）

模式	功能	适用场景
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[] 非空——若为空，说明查询/意图过于狭窄；放宽条件后重试。结果为空时不要声称成功。
4. include_content 中的正文不是拦截页——在 content 中搜索 captcha、Just a moment、Access Denied、cf-browser-verification（与 scrape 使用相同列表）。丢弃受污染的行。
5. 检查相关性是否合理——如果排名靠前的 relevance_score 较低或偏离主题，请细化 intent（而不仅仅是 query）。

风险信号

• 只传入 query 而不提供 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 — 当你不需要意图排序时，使用关键词 SERP（bdata search）。
• js-sdk-best-practices / python-sdk-best-practices — client.discover() 选项详情。