Run a search

Use the Bright Data Marketplace Archive API to run a Search. POST /webarchive/search manages web archive snapshots; returns 200 OK with JSON status.

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": "24h",
    "domain_whitelist": [
      "example.com"
    ],
    "domain_like_whitelist": [
      "%.example.%",
      "example%"
    ],
    "domain_regex_whitelist": [
      ".*example..*"
    ],
    "category_whitelist": [
      "Motor Vehicles"
    ],
    "url_like_whitelist": [
      "%/products/%",
      "%/search%"
    ],
    "url_regex_whitelist": [
      ".*/products/.*"
    ],
    "language_whitelist": [
      "eng"
    ],
    "ip_country_whitelist": [
      "us",
      "ie",
      "in"
    ],
    "captcha": true,
    "robots_block": true
  }
}
'

200

Async (Still Running)

{
  "search_id": "ucd_abc123xyz"
}

POST /webarchive/search searches the Bright Data Archive and returns either the full search result object or a search_id you poll for status.

Every search needs a time range. The filters object is required, and it must carry either max_age, or both min_date and max_date. A request with no filters object returns HTTP 400 with "filters" is required.

How to set the search time range

Use max_age for a window relative to now. Write it as a number followed by a unit:

Unit	Meaning	Example
h	Hours	24h
d	Days	7d
mo	Months	3mo
y	Years	1y

Bright Data recommends max_age of 24h for a first search, because recent data is delivered fastest.

curl -X POST https://api.brightdata.com/webarchive/search \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "max_age": "24h",
      "domain_whitelist": ["example.com"]
    }
  }'

Use min_date and max_date for a fixed calendar range. Both dates use YYYY-MM-DD format and both must be sent together.

curl -X POST https://api.brightdata.com/webarchive/search \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "min_date": "2026-08-01",
      "max_date": "2026-08-08",
      "domain_whitelist": ["example.com"]
    }
  }'

Send one form or the other, never both. max_age combined with min_date and max_date in the same request is a conflict, and the results are undefined.

For date ranges older than 24 hours, use min_date and max_date rather than max_age. See Data range vs delivery time for how the requested range affects delivery speed.

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 counts 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 · required

Filters that scope the search. The filters object is required, and it must carry a time range: either max_age, or both min_date and max_date.

Show child attributes

Response

200

application/json

Search initiated successfully

Async (Still Running)

Completed within 30s

search_id · string

Returned if search is async

Example:

"ucd_abc123xyz"