Skip to main content
POST
Export search metadata
To use S3 storage delivery, you will first need to do the following:
  • Create an AWS role which gives Bright Data access to your system.
    • During this setup, you will be asked by Amazon for an “external ID” that is used with the role.
    • Your external ID for S3 is your Bright Data Account ID that can be found within Account Settings
  • Once a role is created, you will need to allow the Bright Data delivery role to AssumeRole that role.
    • The Bright Data delivery role is: arn:aws:iam::422310177405:role/brd.ec2.zs-dca-delivery
To use Google Cloud Storage delivery, create a bucket and provide the required GCP delivery settings.
The webhook delivery strategy is not suitable for large exports unless you are hosting the webhook on your own infrastructure. Third-party inspection tools such as webhook.site impose strict request body size limits and will fail to receive payloads that can reach up to 1 GB in size. For large deliveries, use Amazon S3, Azure Blob Storage or Google Cloud Storage instead.
Common export parameters:
  • search_id (required): The search ID from a completed search
  • max_entries (optional): Limit the number of files to include in this export
  • delivery (required): Delivery configuration (S3, Azure, GCP, webhook or email)
Amazon S3Choose one authentication method:
  • IAM role: Set assume_role.role_arn. You can also provide assume_role.external_id; if omitted, it defaults to your Bright Data Account ID. Configure your role’s trust policy to allow arn:aws:iam::422310177405:role/brd.ec2.zs-dca-delivery to assume it.
  • Access keys: Set credentials.access_key_id and credentials.secret_access_key.
Do not provide both an IAM role and access keys. The region defaults to us-east-1.Alibaba OSSSet credentials.access_key_id and credentials.secret_access_key to authenticate.Bucket and prefix requirementsFor both Amazon S3 and Alibaba OSS:
  • Bucket names must not contain /.
  • Prefixes must not end with /.
Email delivery:
  • one download link per part
  • links expire after 7 days
If you’re running a linux/macos machine, you can simulate one of our delivery webhooks with the code on this page.

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:

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

Body

application/json
search_id
string
required

Search ID from a search with status done, at least one match, and completion within the last 24 hours.

Example:

"YOUR_SEARCH_ID"

delivery
Email · object
required

Delivery configuration for metadata exports.

max_entries
integer

Maximum number of rows to export. Defaults to all matches when omitted, subject to export limits.

Required range: 1 <= x <= 20000000
Example:

1000

format
enum<string>
default:csv

Export format. Only CSV is supported.

Available options:
csv
exclude_fields
enum<string>[]

Metadata only. Unique column names to omit; at least one column must remain. Rejected by the URLs endpoint.

Available options:
language,
url_path,
domain,
ip_country,
size,
file_path,
robots_block,
captcha_status,
category

Response

Metadata export created successfully.

export_id
string
required

ID of the created metadata export.

Example:

"ucd_abc123xyz-metadata-1762257600000"

rows
integer
required

Number of rows included in the export.

Example:

1000

cost_usd
number
required

Export cost in US dollars.

Example:

0.2

status
string
required

Export status at creation.

Example:

"pending"