cURL
curl --request POST \
--url https://api.brightdata.com/datasets/filter \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"dataset_id": "gd_l1viktl72bvl7bjuj0",
"filter": {
"name": "name",
"operator": "=",
"value": "John"
},
"records_limit": 1000
}
'import requests
url = "https://api.brightdata.com/datasets/filter"
payload = {
"dataset_id": "gd_l1viktl72bvl7bjuj0",
"filter": {
"name": "name",
"operator": "=",
"value": "John"
},
"records_limit": 1000
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
dataset_id: 'gd_l1viktl72bvl7bjuj0',
filter: {name: 'name', operator: '=', value: 'John'},
records_limit: 1000
})
};
fetch('https://api.brightdata.com/datasets/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.brightdata.com/datasets/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'dataset_id' => 'gd_l1viktl72bvl7bjuj0',
'filter' => [
'name' => 'name',
'operator' => '=',
'value' => 'John'
],
'records_limit' => 1000
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.brightdata.com/datasets/filter"
payload := strings.NewReader("{\n \"dataset_id\": \"gd_l1viktl72bvl7bjuj0\",\n \"filter\": {\n \"name\": \"name\",\n \"operator\": \"=\",\n \"value\": \"John\"\n },\n \"records_limit\": 1000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.brightdata.com/datasets/filter")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"dataset_id\": \"gd_l1viktl72bvl7bjuj0\",\n \"filter\": {\n \"name\": \"name\",\n \"operator\": \"=\",\n \"value\": \"John\"\n },\n \"records_limit\": 1000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.brightdata.com/datasets/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"dataset_id\": \"gd_l1viktl72bvl7bjuj0\",\n \"filter\": {\n \"name\": \"name\",\n \"operator\": \"=\",\n \"value\": \"John\"\n },\n \"records_limit\": 1000\n}"
response = http.request(request)
puts response.read_body{
"snapshot_id": "<string>"
}{
"validation_errors": [
"\"filter.filters[0].invalid_prop\" 不被允许",
"\"records_limit\" 必须是正数"
]
}{
"error": "您当前的余额不足以处理此数据采集请求。请向账户添加资金或调整请求以继续。($1 缺失)"
}{
"error": "提供的过滤条件未匹配到任何记录"
}{
"error": "每个数据集的最大任务限制 25 已超出"
}数据集市场 API
筛选数据集
对 900+ 个 Bright Data 市场数据集运行异步筛选任务。返回可下载的 snapshot_id,支持最大 200 MiB 的 CSV/JSON 上传。
POST
/
datasets
/
filter
cURL
curl --request POST \
--url https://api.brightdata.com/datasets/filter \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"dataset_id": "gd_l1viktl72bvl7bjuj0",
"filter": {
"name": "name",
"operator": "=",
"value": "John"
},
"records_limit": 1000
}
'import requests
url = "https://api.brightdata.com/datasets/filter"
payload = {
"dataset_id": "gd_l1viktl72bvl7bjuj0",
"filter": {
"name": "name",
"operator": "=",
"value": "John"
},
"records_limit": 1000
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
dataset_id: 'gd_l1viktl72bvl7bjuj0',
filter: {name: 'name', operator: '=', value: 'John'},
records_limit: 1000
})
};
fetch('https://api.brightdata.com/datasets/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.brightdata.com/datasets/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'dataset_id' => 'gd_l1viktl72bvl7bjuj0',
'filter' => [
'name' => 'name',
'operator' => '=',
'value' => 'John'
],
'records_limit' => 1000
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.brightdata.com/datasets/filter"
payload := strings.NewReader("{\n \"dataset_id\": \"gd_l1viktl72bvl7bjuj0\",\n \"filter\": {\n \"name\": \"name\",\n \"operator\": \"=\",\n \"value\": \"John\"\n },\n \"records_limit\": 1000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.brightdata.com/datasets/filter")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"dataset_id\": \"gd_l1viktl72bvl7bjuj0\",\n \"filter\": {\n \"name\": \"name\",\n \"operator\": \"=\",\n \"value\": \"John\"\n },\n \"records_limit\": 1000\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.brightdata.com/datasets/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"dataset_id\": \"gd_l1viktl72bvl7bjuj0\",\n \"filter\": {\n \"name\": \"name\",\n \"operator\": \"=\",\n \"value\": \"John\"\n },\n \"records_limit\": 1000\n}"
response = http.request(request)
puts response.read_body{
"snapshot_id": "<string>"
}{
"validation_errors": [
"\"filter.filters[0].invalid_prop\" 不被允许",
"\"records_limit\" 必须是正数"
]
}{
"error": "您当前的余额不足以处理此数据采集请求。请向账户添加资金或调整请求以继续。($1 缺失)"
}{
"error": "提供的过滤条件未匹配到任何记录"
}{
"error": "每个数据集的最大任务限制 25 已超出"
}Bright Data 市场数据集 API 的 Filter 端点可针对 900+ 个市场数据集中的任意一个运行大型或基于文件的筛选任务,并返回一个
从账户设置获取您的 Key。
如有超出上述限制的复杂筛选需求,请联系您的客户经理。
Filter 返回一个
此筛选可匹配
使用
例如,
此筛选匹配
响应与 JSON 模式返回的
文件中的值必须与数据集字段格式完全一致。
一次请求中的多个文件也可用于不同字段。以下示例组合了行业文件和地区文件:
任务完成后,将
snapshot_id,任务完成后即可用它下载数据。
将您的 API Key 粘贴到授权字段。要获取 API Key,请创建账户并了解如何生成 API Key。
何时使用 Filter?
对于可接受异步处理的批量或基于文件的任务,使用 Filter:- 按字段值筛选市场数据集,例如国家、价格或布尔标志。
- 查找文本字段包含某个值的记录。
- 按精确值列表匹配记录。
- 按 CSV 或 JSON 文件中的大型值列表筛选,例如排除 10 万以上的公司 ID。
- 超过 1,000 条记录的批量导出。
- Search 尚不支持的数据集。
Filter 如何工作?
- 调用 Filter 端点会启动一个异步任务,并在您的账户中创建一份筛选数据的快照。
- 端点返回
snapshot_id,而不是筛选后的记录。 - 任务最长运行时间为 5 分钟。运行超时的任务将被取消。
- 按快照中的每条记录计费,采用标准市场费率 $2.5 CPM。
- Filter 适用于全部 900+ 个市场数据集。
- 筛选组的最大嵌套深度为 3 层。
如何进行身份验证?
Filter 使用 Bearer token 身份验证。在Authorization 请求头中传入您的 API Key:
Authorization: Bearer YOUR_API_KEY
Filter 有哪些限制?
| 限制 | 值 | 说明 |
|---|---|---|
| 每个文件最大行数 | 10,000 | 每个上传的 CSV/JSON 文件最多可包含 10,000 行数据。表头行不计入。 |
| 每次请求最大文件数 | 无限制 | 一次 multipart 请求中可附加任意数量的文件,只要总大小不超过 200 MiB 上限。 |
| 最大请求大小 | 200 MiB | 所有上传文件和表单数据的总大小。超过 200 MiB 的请求会被拒绝。 |
| 任务超时 | 5 分钟 | 如果筛选在 5 分钟内未完成,任务将被取消。 |
| 筛选嵌套深度 | 3 层 | 使用 and/or 的嵌套筛选组的最大深度。 |
| 最大并行任务数 | 每个数据集 25 个 | 每个数据集最多可同时有 25 个 Filter 任务处于运行中(快照状态为 building)。在有运行中的任务完成之前,新请求将返回 429。 |
| 速率限制 | 5 次/分钟,120 次/小时 | Filter API 调用次数上限。两项限制同时适用。 |
如何使用 JSON 请求进行筛选?
当筛选值可以直接放入请求时,使用 JSON 模式。将dataset_id、records_limit 和 filter 放在 JSON 请求体中,并将 Content-Type 设为 application/json:
curl -X POST "https://api.brightdata.com/datasets/filter" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "gd_l1viktl72bvl7bjuj0",
"records_limit": 100,
"filter": {
"name": "name",
"operator": "includes",
"value": "John"
}
}'
snapshot_id:
{ "snapshot_id": "s_m123456789" }
Filter 接受哪些请求字段?
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
dataset_id | string | 是 | 要筛选的市场数据集 ID。在 multipart 模式下,作为查询参数发送。 |
records_limit | integer | 否 | 快照中包含的最大记录数。在 multipart 模式下,作为查询参数发送。 |
filter | object | 是 | 单字段筛选、筛选组或空值检查。 |
filter.name | string | 是 | 用于筛选的数据集字段。使用获取数据集元数据列出字段名称。 |
filter.operator | string | 是 | 字段与 value 的匹配方式,例如 =、in、includes 或 >=。 |
filter.value | string、number、boolean、array 或文件名 | 是,is_null 和 is_not_null 除外 | 运算符用于比较的值。在 multipart 模式下,为上传文件的名称。 |
如何按字段类型筛选?
每个字段筛选由字段名称、运算符和值组成。以下示例按字段类型展示常用运算符。完整的运算符表、筛选组和嵌套规则,请参阅筛选语法参考。文本字段
使用includes 匹配字段包含该值的记录:
{ "name": "name", "operator": "includes", "value": "John" }
John Smith、Johnson 和 Senior John Account Manager 等值。使用 not_includes 可排除这些记录。
精确值列表
使用in 匹配字段值恰好为列表中某个值的记录:
{ "name": "country", "operator": "in", "value": ["US", "GB", "DE"] }
not_in 排除字段值在列表中的记录。
何时使用 includes 而不是 in?
| 运算符 | 适用场景 | 匹配方式 |
|---|---|---|
includes | 需要匹配包含某个值的文本 | 部分匹配 |
in | 已有明确的允许值列表 | 仅精确匹配 |
includes 搭配 engineer 可匹配 Sales Engineer 和 Engineering Manager,而 in 搭配 ["Sales Engineer"] 仅匹配 Sales Engineer。
布尔字段
使用= 搭配 true 或 false:
{ "name": "verified", "operator": "=", "value": true }
数值字段
数值字段支持=、!=、<、<=、>、>=、in、not_in、is_null 和 is_not_null:
{ "name": "price", "operator": ">=", "value": 100 }
日期范围
在and 组中组合 >= 和 <= 以匹配日期范围:
{
"operator": "and",
"filters": [
{ "name": "created_at", "operator": ">=", "value": "2026-01-01" },
{ "name": "created_at", "operator": "<=", "value": "2026-01-31" }
]
}
数组字段
使用array_includes 匹配多值字段中包含某个精确值的记录:
{ "name": "categories", "operator": "array_includes", "value": "Electronics" }
categories 数组包含 Electronics 的记录。使用 not_array_includes 可排除这些记录。
空字段
使用is_not_null 仅保留字段有值的记录,或使用 is_null 匹配字段为空的记录。这两个运算符不需要 value:
{ "name": "reviews_count", "operator": "is_not_null" }
如何使用 CSV 或 JSON 文件上传进行筛选?
当您需要按大型值列表筛选时,使用文件上传。以multipart/form-data 发送请求,将 dataset_id 和 records_limit 作为查询参数传入,并将每个筛选的 value 设为上传文件的名称:
curl -X POST "https://api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije&records_limit=100" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F 'filter={"operator":"and","filters":[{"name":"industries:value","operator":"includes","value":"industries.csv"}]}' \
-F 'files[]=@/path/to/industries.csv'
snapshot_id 对象相同。
如何格式化 CSV 或 JSON 文件?
- CSV
- JSON
- 第一行必须是与筛选字段名称匹配的表头。
- 后续每行包含单个值。
- 文件只能包含一列。
- 不支持空行和仅包含空格的行。
Example: industries.csv
industries:value
Accounting
Ad Network
Advertising
- 文件必须是对象数组,每个对象的键与筛选字段名称匹配。
Example: industries.json
[
{"industries:value": "Accounting"},
{"industries:value": "Ad Network"},
{"industries:value": "Advertising"}
]
哪些运算符接受文件引用?
文件引用仅可与in、not_in、includes、not_includes、array_includes 和 not_array_includes 配合使用。各运算符如何处理文件,请参阅筛选语法参考。
如何按超过 10,000 个值筛选?
将这些值拆分为每个最多 10,000 行的文件,并在一次请求中全部附加。以下示例排除分布在三个文件中的公司 ID:curl -X POST "https://api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije&records_limit=5000" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F 'filter={"operator":"and","filters":[{"name":"company_id","operator":"not_in","value":"exclude1.csv"},{"name":"company_id","operator":"not_in","value":"exclude2.csv"},{"name":"company_id","operator":"not_in","value":"exclude3.csv"}]}' \
-F 'files[]=@exclude1.csv' \
-F 'files[]=@exclude2.csv' \
-F 'files[]=@exclude3.csv'
curl -X POST "https://api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F 'filter={"operator":"and","filters":[{"name":"industries:value","operator":"includes","value":"industries.csv"},{"name":"region","operator":"in","value":"regions.csv"}]}' \
-F 'files[]=@/path/to/industries.csv' \
-F 'files[]=@/path/to/regions.csv'
如何修复文件上传错误?
| 错误或问题 | 原因 | 解决方法 |
|---|---|---|
Only one column in header is allowed | CSV 包含多于一列。 | 使用单列 CSV 文件。 |
One or more lines in the input file contain only space characters and cannot be used for filtering. Please remove any empty or whitespace-only line and try again. | CSV 包含空行或仅含空格的行。 | 删除空行和仅含空格的行。 |
File exceeds allowed size | 请求大于 200 MiB。 | 减小文件大小,或将值拆分到更小的文件中。 |
Too many rows in file | 某个文件包含超过 10,000 行数据。 | 将值拆分到更小的文件中。 |
File not found | 筛选中的文件名与上传的文件不匹配。 | 确保筛选中引用的文件名与上传文件名完全匹配。 |
Invalid file format | CSV 表头或 JSON 键与筛选字段不匹配。 | 检查 CSV 表头是否与筛选字段名称匹配,或确保 JSON 是对象数组。 |
Field not found | 数据集中不存在该字段。 | 使用获取数据集元数据核对字段名。 |
Filter 返回什么?
Filter 返回snapshot_id,即该请求创建的筛选快照的 ID:
{ "snapshot_id": "s_m123456789" }
snapshot_id 用于快照端点:
Filter 的费用是多少?
Filter 的费用为 $2.5 CPM(每返回 1,000 条记录),与市场价格相同。筛选返回 0 条记录时不收费。Filter 可能返回哪些错误?
| 状态码 | 含义 | 处理方式 |
|---|---|---|
400 | 筛选或参数有误 | 使用获取数据集元数据核对字段名。 |
401 | API Key 错误或缺失 | 在 Authorization 请求头中发送有效的 API Key。 |
402 | 余额不足 | 充值或减小 records_limit。 |
404 | 未知的 dataset_id | 确认数据集 ID。 |
422 | 筛选未匹配任何记录 | 放宽筛选条件或检查字段值。 |
429 | 并行任务过多(每个数据集最多 25 个运行中任务)或触发速率限制(5 次/分钟或 120 次/小时) | 等待运行中的任务完成,然后以退避方式重试。如需减少任务数量,可将兼容的筛选条件合并为一个范围更广的任务。 |
相关文档
- 数据集列表,查找可用的市场数据集。
- 获取数据集元数据,查看数据集字段和类型。
- 筛选语法参考,了解所有运算符、筛选组和嵌套。
- Search 数据集(同步),用于实时查询。
- Dataset API 概述
授权
在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。
认证方法:
- 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users
- 在请求的 Authorization 头中包含 API Key
- 格式:
Authorization: Bearer YOUR_API_KEY
示例:
Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df
了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key?
查询参数
请求体
application/jsonmultipart/form-data
此页面对您有帮助吗?