> ## Documentation Index
> Fetch the complete documentation index at: https://similarweb-zp8zf.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch API Request - Step-by-Step Walkthrough

This guide provides a step-by-step walkthrough for using Similarweb's Batch API to make a report request. You'll submit a batch job, check its status, and finally download the results once processing is complete.

<AccordionGroup>
  <Accordion title="1. Batch API Request Endpoint">
    The Batch API request is a POST request to this endpoint. It will initiate the batch job.
  </Accordion>

  <Accordion title="2. Request Headers">
    The POST request has the following headers:
    API-key: Include your unique API key in the request header.

    Content-Type: Set to application/json to indicate you are sending JSON data.
  </Accordion>

  <Accordion title="3. Request Body">
    The actual request is incorporated in the body. In this section you can configure all the report parameters such as the dataset, metrics, dates, and more
  </Accordion>

  <Accordion title="4. Delivery Information">
    Here you can configure output definitions such as response format (e.g., csv) and delivery method for the report (download link, integrations, etc)
  </Accordion>

  <Accordion title="5. Dataset / Data Table">
    Define the dataset you're looking to query (vtable). For a full list of available datasets use the Batch Describe endpoint.
  </Accordion>

  <Accordion title="6. Build you Report / Query">
    Based on the dataset you chose, you can now build your report including:
    granularity, filters (e.g., domains, countries, subdomains), metrics, and date range for the data you want to pull.
  </Accordion>

  <Accordion title="7. Submit the Request">
    Submit the request using a tool like cURL, Postman, or any API client.

    Upon successful submission, you'll receive a response with a report\_id. This report\_id is crucial for the next steps, as it allows you to track the report's progress.
  </Accordion>

  <Accordion title="8. Monitor Request Status">
    Use the /request-status endpoint to check if your batch job is complete.

    In your request to /request-status, provide the request\_id received in the previous step.

    Poll the request status endpoint periodically until you receive a status of complete. This indicates that the report is ready.
  </Accordion>

  <Accordion title="9. Retrieve the Report">
    Once the job status is complete, you'll receive a response with a download link.

    Use the provided download link to access your report.
  </Accordion>
</AccordionGroup>

<RequestExample>
  ```bash Request theme={null}
  curl --location 'https://api.similarweb.com/batch/v4/request-report' \
  --header 'api-key: {{API_KEY}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "delivery_information": {
      "response_format": "csv",
      "delivery_method": "download_link"
    },
    "report_query": {
      "tables": [
        {
          "vtable": "traffic_and_engagement",
          "granularity": "monthly",
          "filters": {
            "domains": [
              "amazon.com",
              "ebay.com",
              "etsy.com",
              "aliexpress.com"
            ],
            "countries": [
              "WW"
            ],
            "include_subdomains": true
          },
          "metrics": [
            "all_traffic_visits",
            "mobile_visits",
            "desktop_visits",
            "desktop_unique_visitors",
            "mobile_unique_visitors",
            "all_page_views"
          ],
          "start_date": "2024-04",
          "end_date": "2024-09"
        }
      ]
    }
  }'
  ```

  ```json Response theme={null}
  {
    "report_id": "845d6850-79d1-4125-964e-eaef0d6923e5",
    "status": "pending"
  }
  ```
</RequestExample>

<ResponseExample>
  ```bash Report Request theme={null}
  curl --location 'https://api.similarweb.com/v3/batch/request-status/{report_id}' \
  --header 'api-key: {{API_KEY}}' \
  --header 'Content-Type: application/json' \
  ```

  ```json Report Response theme={null}
  {
    "data_points_count": 1779429,
    "download_url": "example_url.com",
    "status": "completed",
    "used_quota": 35589
  }
  ```
</ResponseExample>