Report Endpoints

In this section, we'll go over:

1. Validate Report - Get the data credits calculation and warnings
2. Report Status - Get the current status and download URL
3. Retry Endpoint

1. POST Request validate

Before running your report, you can use our Request validate endpoint to calculate the estimated credits the report will cost, and if the report has any warnings or alerts.

Simply use the same code you are using with your Request Report in the set up your batch API section and change the URL to this:

https://api.similarweb.com/batch/v4/request-validate

{
   "delivery_information": 
  	{
    	"response_format": "csv"
  	},
  "report_query": {
    "tables": [
      {
        "vtable": "traffic_and_engagement",
        "granularity": "monthly",
        "filters": {
          "domains": [
            "similarweb.com",
            "api.similarweb.com"
          ],
          "countries": [
            "WW",
            "US"
          ],
          "include_subdomains": true
        },
        "metrics": [
          "all_traffic_visits",
          "desktop_new_visitors",
          "desktop_pages_per_visit",
          "desktop_returning_visitors"
        ],
        "start_date": "2023-02",
        "end_date": "2024-02"
      }
    ]
  }
}

{
    "estimated_credits": 208,
    "is_valid": true,
    "warnings": []
}

{
    "errors": [
        "granularity should be one of the following - daily, weekly, monthly."
    ],
    "is_valid": false,
    "warnings": []
}

2. GET Request Report Status

https://api.similarweb.com/v3/batch/request-status/{{GENERATED-REPORT-ID}}

import requests

url = "https://api.similarweb.com/v3/batch/request-status/{{generated_report_id}}"

payload={}
headers = {
  'api-key': '{{your_api_key}}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

Example response:

{
    "data_points_count": 1779429,
    "download_url": "example_url.com",
    "status": "completed",
    "used_quota": 35589
}

{
    "status": "pending"
}

👍

The download link will remain valid for 30 days. We recommend saving these for a certain time period just in case you will need our assistance to troubleshoot any issue that may occur.

Once submitted, a request will have a report_id identifier and with it, you can track its status, the statuses are:

'pending'- The request is valid, the request was not charged yet and is waiting to start report generation.

'processing' - The request has been charged and has started report generation.

'completed' - Report generation has finished successfully and the report is ready.

'retry' - The report is about to retry (after some failure), the request was not yet charged, and report generation hasn't started yet.

'bad_request' - The request is not valid, and potential errors - incorrect dates, unavailable countries, unavailable metrics, etc...

'internal_error' - Internal server error. An unexpected error has occurred on our servers. It is recommended to use the retry mechanism.

3. POST Retry report

If your request fails due to an internal error, you can use this retry endpoint with the report ID to re-execute the request.

Your initial failed request will not affect your quota.

https://api.similarweb.com/v3/batch/retry/{{GENERATED-REPORT-ID}}