Report Endpoints

This section walks through three core report endpoints:

1. Validate Report — get the data credits calculation and any warnings before running a report.
2. Report Status — check the current status and download URL.
3. Retry Endpoint — re-execute a failed request.

1. POST Request validate

Before running your report, use the Request validate endpoint to calculate the estimated credits the report will cost and surface any warnings or alerts.

Use the same code from your Request Report and change the URL.

 

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

Request body example

 

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

Response examples

 

  {
  "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/batch/request-status/{{GENERATED-REPORT-ID}}

 

  import requests

url = "https://api.similarweb.com/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 responses

 

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

 

  {
  "status": "pending"
}

Report statuses

Once submitted, a request has a report_id you can use to track its progress through these statuses:

• pending — The request is valid; it has not yet been charged and is waiting to start report generation.
• processing — The request has been charged and report generation has started.
• completed — Report generation finished successfully and the report is ready.
• retry — The report is about to retry after a failure; the request was not yet charged.
• bad_request — The request is not valid (for example, incorrect dates, unavailable countries, unavailable metrics).
• internal_error — Unexpected server-side error. Use the retry mechanism.

3. POST Retry report

If your request fails due to an internal error, 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/batch/retry/{{GENERATED-REPORT-ID}}