Filter Dataset (JSON or File Uploads)

Create a dataset snapshot based on a provided filter

POST /datasets/filter

cURL

cURL

curl --request POST \
  --url https://api.brightdata.com/datasets/filter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'filter={
  "name": "name",
  "operator": "=",
  "value": "John"
}'

200

{
  "snapshot_id": "<string>"
}

Paste your API key into the authorization field. To get an API key, Create an account and learn how to generate an API key.

General Description

• This endpoint filters a dataset and creates a snapshot of the filtered data in your account.
• The job runs asynchronously and can take up to 5 minutes to complete. If it exceeds this time, it will be cancelled.
• Charges apply based on the size of the snapshot and per-record pricing.
• Filters can have up to 3 levels of nested filter groups.
• You can upload CSV or JSON files for efficient filtering when handling large sets of values.

---

File Format Requirements

CSV

• First line must be a header matching the field name in your filter.
• Each following line contains a single value.

Example: industries.csv

industries:value
Accounting
Ad Network
Advertising

JSON

• Must be an array of objects, each with a key matching the field name in your filter.

Example industries.json

[
  {"industries:value": "Accounting"},
  {"industries:value": "Ad Network"},
  {"industries:value": "Advertising"}
]

---

Filter Syntax with File References

When using file uploads, reference the filename in the filter’s value field.

Example

{
  "operator": "and",
  "filters": [
    {
      "name": "industries:value",
      "operator": "includes",
      "value": "industries.csv"
    }
  ]
}

Supported Operators for File References

Operator	Field Types	Description
in	Any	Field value equals any value in file
not_in	Any	Field value does not equal any value in file
includes	Array, Text	Field value contains any value in file
not_includes	Array, Text	Field value does not contain any value in file
array_includes	Array	Any value in file exists in field value
not_array_includes	Array	No values in file exist in field value

---

Example: Filtering with Multiple Files

curl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "files[]=@/path/to/industries.csv" \
  -F "files[]=@/path/to/regions.csv" \
  -F "filter={\"operator\":\"and\",\"filters\":[{\"name\":\"industries:value\",\"operator\":\"includes\",\"value\":\"industries.csv\"},{\"name\":\"region\",\"operator\":\"in\",\"value\":\"regions.csv\"}]}" \
  "api.brightdata.com/datasets/filter?dataset_id=gd_l1vijqt9jfj7olije"

Troubleshooting

Issue	Possible Solution
”File not found”	Make sure the filename in your filter exactly matches the uploaded file name.
”Invalid file format”	Check CSV header matches the filter field name, or ensure JSON is an array of objects.
”Field not found”	Verify field exists in dataset. Use Get Dataset Metadata.

Related Documentation

• Get Dataset List
• Get Dataset Metadata

Authorizations

Authorization · string · header · required

在 Authorization 头中使用您的 Bright Data API Key 作为 Bearer token。

认证方法:

1. 从 Bright Data 账户设置获取您的 API Key: https://brightdata.com/cp/setting/users
2. 在请求的 Authorization 头中包含 API Key
3. 格式: Authorization: Bearer YOUR_API_KEY

示例:

Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

了解如何获取 Bright Data API Key: https://docs.brightdata.com/cn/api-reference/authentication#如何生成新的-api-key？

Query Parameters

dataset_id · string · required

要筛选的数据集 ID（在 multipart/form-data 模式下为必填）

Example:

"gd_l1viktl72bvl7bjuj0"

records_limit · integer

限制包含在快照中的记录数量

Example:

1000

Body

multipart/form-data

filter · 单字段筛选器 · object · required

单字段筛选器

筛选器组

无值单字段筛选器

Show child attributes

Example:

{
  "name": "name",
  "operator": "=",
  "value": "John"
}

Response

200

application/json

创建快照的任务已成功启动

snapshot_id · string

快照 ID