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/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