Bright Data 市场数据集 API 的 Search 端点对市场数据集运行实时、基于 Elasticsearch 的查询：发送一个 filter，即可在响应中以亚秒级延迟取回记录。
何时使用 Search？
当您需要在单次低延迟调用中取回少量记录时，使用 Search：
- 实时查询，例如线索一进入 CRM 就立即增强。
- 将实时记录输入 AI agent 或 LLM 应用。
- 按姓名、职位、公司或地区进行销售勘探。
- 购买前抽样数据集，搭配
"sort": "random"。
- 任何需要在一次调用中取回最多 1,000 条记录的工作负载。
如果您需要文件上传、批量导出，或某个不在支持列表中的数据集，请改用 Filter。
运行您的第一个 Search 查询
向 /datasets/search/:dataset_id 发送 POST 请求，并带上一个 filter 对象。下面的示例在 LinkedIn 人物档案数据集中查询 name 包含 Egor 的记录：
curl -X POST "https://api.brightdata.com/datasets/search/gd_l1viktl72bvl7bjuj0" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"size": 10,
"filter": {
"name": "name",
"operator": "includes",
"value": "Egor"
}
}'
{
"hits": [ /* records */ ],
"total_hits": 579859,
"took": 142
}
Search 支持哪些数据集？
Search 处于 alpha 阶段，目前支持三个 LinkedIn 数据集。其他任何数据集请使用 Filter。
| 数据集 | dataset_id |
|---|
| LinkedIn 人物档案 | gd_l1viktl72bvl7bjuj0 |
| LinkedIn 人物档案（含联系方式增强） | gd_me5ppxjr2ge6icjuh0 |
| LinkedIn 公司信息 | gd_l1vikfnt1wgvvqz95w |
Amazon 数据集即将推出。更多数据集将在 2026 年第三季度逐步走向正式发布（GA）。向 Search 传入不受支持的 dataset_id 会返回 404。
如何进行身份验证？
Search 使用 Bearer token 身份验证。在 Authorization 请求头中传入您的 API Key：
Authorization: Bearer YOUR_API_KEY
Search 接受哪些参数？
| 名称 | 类型 | 默认值 | 必填 | 说明 |
|---|
filter | object | - | 是 | 筛选表达式。不能为空。参见筛选语法参考。 |
size | number | 100 | 否 | 返回的记录数量。Search 最适合每次调用最多 1,000 条记录。 |
sort | string 或 array | - | 否 | default、random，或自定义排序，如 [{"timestamp":"asc"}]。 |
search_after | array | - | 否 | 分页游标。传入上一次响应中的 search_after 值。 |
Search 返回什么？
| 名称 | 类型 | 说明 |
|---|
hits | array | 匹配的记录。 |
total_hits | number | 与筛选匹配的记录总数。 |
took | number | 服务器耗时（毫秒）。 |
search_after | array | 下一页的游标。仅在设置了 sort 时返回。 |
如何排序和分页？
设置 sort 控制排序，并使用返回的 search_after 游标翻页。
使用随机排序抽样数据集
使用 "sort": "random" 提取有代表性的样本，例如在购买数据集之前：
curl -X POST "https://api.brightdata.com/datasets/search/gd_l1viktl72bvl7bjuj0" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"size": 10,
"sort": "random",
"filter": { "name": "name", "operator": "includes", "value": "Egor" }
}'
使用 search_after 翻页
设置 "sort": "default" 以在响应中获得 search_after 游标。请求第一页：
{
"size": 10,
"sort": "default",
"filter": { "name": "name", "operator": "includes", "value": "Egor" }
}
search_after 数组传回以获取下一页：
{
"size": 10,
"sort": "default",
"search_after": [ /* value from previous response */ ],
"filter": { "name": "name", "operator": "includes", "value": "Egor" }
}
按自定义字段排序
传入由”字段到方向”对象组成的数组，按指定字段排序：
{ "sort": [{ "timestamp": "asc" }] }
Search 的费用是多少？
Search 的费用为 $2.5 CPM（每返回 1,000 条记录），与市场价格相同。筛选返回 0 条记录时不收费。
Search 可能返回哪些错误？
| 状态码 | 含义 | 处理方式 |
|---|
400 | 筛选或参数有误 | 使用获取数据集元数据核对字段名。 |
401 | API Key 错误或缺失 | 检查您的 Bearer token。 |
402 | 余额不足 | 充值或减小 size。 |
404 | 未知的 dataset_id | 确认数据集在上方的支持列表中。 |
422 | 筛选未匹配任何记录 | 放宽筛选条件或检查字段值。 |
429 | 触发速率限制 | 退避后重试。 |
常见问题
Search 支持 CSV 或 JSON 文件上传吗？
不支持。Elasticsearch 无法在查询时读取外部文件。要按 CSV 或 JSON 文件中的成千上万个值进行筛选，请使用 Filter 端点。
Search 一次调用能返回多少条记录？
Search 最适合每次调用最多 1,000 条记录。如需更大规模的提取，请使用 Filter，它基于快照并支持批量导出。
为什么 Search 和 Filter 返回的结果略有不同？
两个端点使用不同的引擎。Elasticsearch 对文本的分词方式与快照引擎不同，因此自由文本匹配可能存在差异。在自由文本字段上，建议优先使用 includes 运算符而非 =。
相关文档
