> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Export metadata

> Export one metadata row per matched file as gzip-compressed CSV, without page content.

> [!NOTE]
>
> To use S3 storage delivery, you will first need to do the following:
>
> * Create an [AWS role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) 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](https://brightdata.com/cp/setting/customer_details)
> * 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`

> [!NOTE]
>
> To use Google Cloud Storage delivery, create a bucket and provide the required GCP delivery settings.

> [!WARNING]
>
> 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](https://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.

> [!NOTE]
>
> **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)

> [!NOTE]
>
> **Amazon S3**
>
> Choose 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 OSS**
>
> Set credentials.access\_key\_id and credentials.secret\_access\_key to authenticate.
>
> **Bucket and prefix requirements**
>
> For both Amazon S3 and Alibaba OSS:
>
> * Bucket names must not contain /.
> * Prefixes must not end with /.

> [!NOTE]
>
> **Email delivery:**
>
> * one download link per part
> * links expire after 7 days

> [!TIP]
>
> If you’re running a linux/macos machine, you can simulate one of our delivery webhooks with the code on [this page](https://docs.brightdata.com/products/archive/webhook-test).


## OpenAPI

````yaml api-reference/web-archive-api POST /webarchive/dump_metadata
openapi: 3.1.0
info:
  title: BrightData Web Archive API
  version: 1.0.0
  description: API to search and retrieve archived web pages.
servers:
  - url: https://api.brightdata.com
security:
  - bearerAuth: []
paths:
  /webarchive/dump_metadata:
    post:
      summary: Export search metadata
      description: >-
        Creates a CSV metadata export from a completed search using the
        specified delivery strategy. The search must have status `done`, contain
        at least one match, and have completed within the last 24 hours. Use
        your existing API key as a Bearer token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataExportCreateRequest'
            examples:
              EmailDelivery:
                value:
                  search_id: YOUR_SEARCH_ID
                  max_entries: 1000
                  delivery:
                    strategy: email
                    settings:
                      address: you@example.com
      responses:
        '200':
          description: Metadata export created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataExportCreateResponse'
              examples:
                Success:
                  summary: Metadata export pending delivery
                  value:
                    export_id: ucd_abc123xyz-metadata-1762257600000
                    rows: 1000
                    cost_usd: 0.2
                    status: pending
        '400':
          description: >-
            Invalid request or delivery settings; search incomplete or empty;
            invalid account email. Validation responses include `error`,
            `error_code: validation`, and `details`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataExportErrorResponse'
              examples:
                MissingSearchId:
                  summary: Required field missing from the request body
                  value:
                    error: Request validation failed
                    error_code: validation
                    details:
                      - message: '"search_id" is required'
                        path:
                          - search_id
                        type: any.required
        '401':
          description: Unauthorized.
        '402':
          description: Insufficient balance.
        '404':
          description: Search not found for your account.
        '410':
          description: Search completed more than 24 hours ago. Run it again.
        '413':
          description: >-
            More than 20 million rows. Set `max_entries` or narrow the search.
            Oversized exports return `error_code: export_too_large`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataExportTooLargeResponse'
        '500':
          description: Internal error. Contact support with the error text.
components:
  schemas:
    MetadataExportCreateRequest:
      type: object
      required:
        - search_id
        - delivery
      properties:
        search_id:
          type: string
          description: >-
            Search ID from a search with status `done`, at least one match, and
            completion within the last 24 hours.
          example: YOUR_SEARCH_ID
        delivery:
          $ref: '#/components/schemas/MetadataExportDelivery'
        max_entries:
          type: integer
          minimum: 1
          maximum: 20000000
          description: >-
            Maximum number of rows to export. Defaults to all matches when
            omitted, subject to export limits.
          example: 1000
        format:
          type: string
          enum:
            - csv
          default: csv
          description: Export format. Only CSV is supported.
        exclude_fields:
          type: array
          uniqueItems: true
          items:
            type: string
            enum:
              - language
              - url_path
              - domain
              - ip_country
              - size
              - file_path
              - robots_block
              - captcha_status
              - category
          description: >-
            Metadata only. Unique column names to omit; at least one column must
            remain. Rejected by the URLs endpoint.
    MetadataExportCreateResponse:
      type: object
      required:
        - export_id
        - rows
        - cost_usd
        - status
      properties:
        export_id:
          type: string
          description: ID of the created metadata export.
          example: ucd_abc123xyz-metadata-1762257600000
        rows:
          type: integer
          description: Number of rows included in the export.
          example: 1000
        cost_usd:
          type: number
          description: Export cost in US dollars.
          example: 0.2
        status:
          type: string
          description: Export status at creation.
          example: pending
    MetadataExportErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable summary of the failure
        error_code:
          type: string
          description: Machine-readable error category
          example: validation
        details:
          type: array
          description: Per-field validation failures
          items:
            type: object
            properties:
              message:
                type: string
                description: Why the field failed validation
              path:
                type: array
                description: Path to the offending field in the request body
                items:
                  type: string
              type:
                type: string
                description: Validation rule that failed
      description: >-
        Error response. Validation failures include error, error_code set to
        validation, and details.
      allOf:
        - if:
            required:
              - error_code
            properties:
              error_code:
                const: validation
          then:
            required:
              - details
    MetadataExportTooLargeResponse:
      type: object
      required:
        - error
        - error_code
      properties:
        error:
          type: string
          description: Human-readable explanation of the export size limit.
        error_code:
          type: string
          enum:
            - export_too_large
    MetadataExportDelivery:
      description: Delivery configuration for metadata exports.
      oneOf:
        - $ref: '#/components/schemas/MetadataExportEmailDelivery'
          title: Email
        - $ref: '#/components/schemas/S3Delivery'
          title: Amazon S3
        - $ref: '#/components/schemas/AzureDelivery'
          title: Azure Blob
        - $ref: '#/components/schemas/GcpDelivery'
          title: Google Cloud Storage
        - $ref: '#/components/schemas/WebhookDelivery'
          title: Webhook
    MetadataExportEmailDelivery:
      type: object
      required:
        - strategy
        - settings
      properties:
        strategy:
          type: string
          enum:
            - email
        settings:
          $ref: '#/components/schemas/MetadataExportEmailDeliverySettings'
    S3Delivery:
      type: object
      required:
        - strategy
        - settings
      properties:
        strategy:
          type: string
          enum:
            - s3
        settings:
          $ref: '#/components/schemas/S3DeliverySettings'
    AzureDelivery:
      type: object
      required:
        - strategy
        - settings
      properties:
        strategy:
          type: string
          enum:
            - azure
        settings:
          $ref: '#/components/schemas/AzureDeliverySettings'
    GcpDelivery:
      type: object
      required:
        - strategy
        - settings
      properties:
        strategy:
          type: string
          enum:
            - gcp
        settings:
          type: object
          required:
            - bucket
          properties:
            bucket:
              type: string
            prefix:
              type: string
    WebhookDelivery:
      type: object
      required:
        - strategy
        - settings
      properties:
        strategy:
          type: string
          enum:
            - webhook
        settings:
          $ref: '#/components/schemas/WebhookDeliverySettings'
    MetadataExportEmailDeliverySettings:
      type: object
      required:
        - address
      properties:
        address:
          type: string
          format: email
          description: Delivery email address.
          example: you@example.com
    S3DeliverySettings:
      type: object
      required:
        - bucket
        - assume_role
      properties:
        bucket:
          type: string
          description: Target S3 bucket name
        prefix:
          type: string
          description: Optional prefix path inside the bucket
        assume_role:
          $ref: '#/components/schemas/S3AssumeRole'
    AzureDeliverySettings:
      type: object
      required:
        - container
        - credentials
      properties:
        container:
          type: string
          description: Azure Blob Storage container name
        prefix:
          type: string
          description: Optional prefix path inside the container
        credentials:
          $ref: '#/components/schemas/AzureCredentials'
    WebhookDeliverySettings:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          description: Webhook URL to receive notifications about dump delivery status
        auth:
          type: string
          description: Bearer your-optional-auth-token
    S3AssumeRole:
      type: object
      required:
        - role_arn
      properties:
        role_arn:
          type: string
          description: AWS IAM role ARN to assume for delivery
    AzureCredentials:
      type: object
      required:
        - account
        - key
      properties:
        account:
          type: string
          description: Azure storage account name
        key:
          type: string
          description: Azure storage account access key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        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
      bearerFormat: API Key

````