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.

1. Batch API Request Endpoint

The Batch API request is a POST request to this endpoint. It will initiate the batch job.

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.

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

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)

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.

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.

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.

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.

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.

Request

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"
      }
    ]
  }
}'

Report Request

curl --location 'https://api.similarweb.com/v3/batch/request-status/{report_id}' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/json' \