Run a Search

Initiates a search of the archive. If the search takes longer than 30 seconds, the response returns only a search_id and you should poll the status asynchronously. If it completes within 30 seconds, the response returns the full search result object.

POST /webarchive/search

Run a search

cURL

curl --request POST \
  --url https://api.brightdata.com/webarchive/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filters": {
    "max_age": "Duration",
    "min_date": "YYYY-MM-DD",
    "max_date": "YYYY-MM-DD",
    "domain_whitelist": [
      "example.com"
    ],
    "domain_blacklist": [
      "example.com"
    ],
    "domain_regex_whitelist": [
      ".*example..*"
    ],
    "domain_regex_blacklist": [
      ".*example..*"
    ],
    "domain_like_whitelist": [
      "%.example.%",
      "example%"
    ],
    "domain_like_blacklist": [
      "%.example.ca"
    ],
    "category_whitelist": [
      "Automotive"
    ],
    "category_blacklist": [
      "Automotive"
    ],
    "url_regex_whitelist": [
      ".*/products/.*"
    ],
    "url_regex_blacklist": [
      ".*/products/.*"
    ],
    "url_like_whitelist": [
      "%/products/%",
      "%/search%"
    ],
    "url_like_blacklist": [
      "%/review/%"
    ],
    "language_whitelist": [
      "eng"
    ],
    "language_blacklist": [
      "eng"
    ],
    "ip_country_whitelist": [
      "us",
      "ie",
      "in"
    ],
    "ip_country_blacklist": [
      "mx",
      "ae",
      "ca"
    ],
    "captcha": true,
    "robots_block": true
  }
}
'

200

{
  "search_id": "ucd_abc123xyz"
}

Mandatory:
Either use max_age OR a combination of min_date + max_date

If the search takes longer than 30 seconds, the response returns only a search_id and you should poll the status asynchronously. If the search completes within 30 seconds, the response returns the full search result object (same as GET /webarchive/search/<search_id>).

You can run up to 100 searches per day without triggering a dump. Once you trigger a dump, that search no longer count against your limit.

LIKE vs Regex Filters

• Use LIKE filters (domain_like_*, url_like_*) for simple pattern matching with % (any sequence) and _ (single character).
• LIKE patterns are case-insensitive and often faster than regex for simple prefix/suffix matching like %.com or amazon%.
• Use regex filters (domain_regex_*, url_regex_*) for complex patterns requiring full regex syntax. LIKE patterns use backslash escaping: \% for literal %, \_ for literal _.

Authorizations

Authorization · string · header · required

Use your Bright Data API Key as a Bearer token in the Authorization header.

How to authenticate:

1. Obtain your API Key from the Bright Data account settings at https://brightdata.com/cp/setting/users
2. Include the API Key in the Authorization header of your requests
3. Format: Authorization: Bearer YOUR_API_KEY

Example:

Authorization: Bearer b5648e1096c6442f60a6c4bbbe73f8d2234d3d8324554bd6a7ec8f3f251f07df

Learn how to get your Bright Data API key: https://docs.brightdata.com/api-reference/authentication

Body

application/json

filters · object

Show child attributes

Response

200

application/json

Search initiated successfully

Option 1

Option 2

search_id · string

Returned if search is async

Example:

"ucd_abc123xyz"