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.
curl --location 'https://api.similarweb.com/batch/v5/request-report' \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.
--header 'api-key: {{API_KEY}}' \--header 'Content-Type: application/json' \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
--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" } ] }}'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)
"delivery_information": { "response_format": "csv", "delivery_method": "download_link" },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.
"vtable": "traffic_and_engagement",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.
"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"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.
{ "report_id": "845d6850-79d1-4125-964e-eaef0d6923e5", "status": "pending"}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.
curl --location 'https://api.similarweb.com/v3/batch/request-status/{report_id}' \--header 'api-key: {{API_KEY}}' \--header 'Content-Type: application/json' \---------------------------------------------------------------------------------------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.
"data_points_count": 1779429, "download_url": "example_url.com", "status": "completed", "used_quota": 35589}
On this page
- Batch API Request - Step-by-Step Walkthrough