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": "每个数据集的最大任务限制 100 已超出"
}数据集市场 API
筛选数据集 (BETA)
对 250+ 个 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": "每个数据集的最大任务限制 100 已超出"
}Bright Data 市场数据集 API 的 Filter 端点针对 250+ 个市场数据集中的任意一个运行大体量或基于文件的筛选任务,并返回一个
从账户设置获取您的 Key。
Filter 返回一个
要排除 10 万以上的值,将它们拆分为每个最多 10,000 行的文件,并在一次请求中全部附加:
有关 CSV 和 JSON 文件格式规则、文件引用以及上传故障排除,请参阅使用 CSV/JSON 文件筛选数据集。
snapshot_id,您可在任务完成后下载。
将您的 API Key 粘贴到授权字段。要获取 API Key,请创建账户并了解如何生成 API Key。
何时使用 Filter?
对于可接受异步处理的批量或基于文件的任务,使用 Filter:- 超过 1,000 条记录的批量导出。
- 按 CSV 或 JSON 文件中的大型值列表筛选,例如排除 10 万以上的公司 ID。
- Search 尚不支持的数据集。
- 可接受异步的计划任务或后台管道。
Filter 如何工作?
- 调用 Filter 端点会启动一个异步任务,并在您的账户中创建一份筛选数据的快照。
- 任务最长运行时间为 5 分钟。运行超时的任务将被取消。
- 按快照中的每条记录计费,采用标准市场费率 $2.5 CPM。
- Filter 适用于全部 250+ 个市场数据集。
- 筛选组的最大嵌套深度为 3 层。
如何进行身份验证?
Filter 使用 Bearer token 身份验证。在Authorization 请求头中传入您的 API Key:
Authorization: Bearer YOUR_API_KEY
限制
| 限制 | 值 | 说明 |
|---|---|---|
| 每个文件最大行数 | 10,000 | 每个上传的 CSV/JSON 文件最多可包含 10,000 行数据。表头行不计入。 |
| 每次请求最大文件数 | 无限制 | 一次 multipart 请求中可附加任意数量的文件,只要总大小不超过 200 MiB 上限。 |
| 最大请求大小 | 200 MiB | 所有上传文件和表单数据的总大小。超过 200 MiB 的请求会被拒绝。 |
| 任务超时 | 5 分钟 | 如果筛选在 5 分钟内未完成,任务将被取消。 |
| 筛选嵌套深度 | 3 层 | 使用 and/or 的嵌套筛选组的最大深度。 |
| 最大并行任务数 | 每个数据集 100 个 | 每个数据集最多可同时运行 100 个 Filter 任务。 |
| 速率限制 | 120 次/小时 | 每小时最多的 Filter API 调用次数。 |
如何调用 Filter?
Filter 有两种模式:JSON 用于普通筛选,multipart 用于文件上传。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": "=",
"value": "John"
}
}'
snapshot_id:
{ "snapshot_id": "s_abc123..." }
Multipart 模式(文件上传)
将dataset_id 和 records_limit 作为查询参数发送,将 filter 和上传的文件放在 form-data 请求体中。将 Content-Type 设为 multipart/form-data:
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'
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'
Filter 返回什么?
Filter 返回一个snapshot_id。在任务完成后,使用它通过快照 API 下载筛选后的记录:
Filter 的费用是多少?
Filter 的费用为 $2.5 CPM(每返回 1,000 条记录),与市场价格相同。筛选返回 0 条记录时不收费。Filter 可能返回哪些错误?
| 状态码 | 含义 | 处理方式 |
|---|---|---|
400 | 筛选或参数有误 | 使用获取数据集元数据核对字段名。 |
401 | API Key 错误或缺失 | 检查您的 Bearer token。 |
402 | 余额不足 | 充值或减小 records_limit。 |
404 | 未知的 dataset_id | 确认数据集 ID。 |
422 | 筛选未匹配任何记录 | 放宽筛选条件或检查字段值。 |
429 | 并行任务过多(每个数据集最多 100 个)或触发速率限制(120 次/小时) | 退避后重试。 |
筛选语法
filter 对象及其运算符、筛选组和嵌套规则与 Search 端点共享,并集中记录在一处。完整的运算符列表、筛选组、最多 3 层嵌套以及 CSV/JSON 文件引用,请参阅筛选语法参考。
相关文档
授权
在 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?
查询参数
要过滤的数据集 ID(在 multipart/form-data 模式下为必填)
示例:
"gd_l1viktl72bvl7bjuj0"
限制快照中包含的记录数量
示例:
1000
请求体
application/jsonmultipart/form-data
响应
快照创建任务已成功启动
快照 ID
此页面对您有帮助吗?