Similarweb

Getting Started

Introduction

What's New in V5

Authentication

Making Your First Request

Guides

Available Data

Popular Use Cases

REST API vs Batch API

API Pricing & Data Credits

Error Handling & Troubleshooting

API Reference

<p class="slate-p " >Endpoints returning traffic and engagement statistics.</p><p class="slate-p " ></p><p class="slate-p " ></p>

Web Intelligence API

Search Intelligence API

Sales Intelligence API

App Intelligence API

Gen AI Intelligence API

The Similarweb Batch API gives you scalable access to one of the world's largest digital measurement databases. Use this section to set up your account, learn how to request reports, configure webhooks, and handle errors and country codes.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Batch API and REST API use different authentication keys. Make sure you're using your <strong class="slate-bold">Batch API key</strong> when calling these endpoints.</p>
</Callout>


Batch API Reference

Welcome to Similarweb's Batch API — giving you scalable access to the world's largest digital measurement database. Get Similarweb data for more than 1,000,000 domains and 5 years of history, with tens of metrics, in one API call.

This guide walks you through the two main steps required to get millions of data points from the API.

## Get started checklist

*   🔑 [Get an API Key tutorial](https://developers.similarweb.com/docs/authentication), or generate a new key directly from your [account](https://account.similarweb.com/batch-api?from=developershub)
*   📈 Choose the data and metrics you need based on your subscription on [datahub.similarweb.com](https://dash.readme.com/go/similarweb?redirect=%2Fv4.0%2Fdocs%2Fdatahub) or discover new datasets [here](https://smwb-batch-api.streamlit.app/)
*   📝 Create a request report with a valid JSON body
*   🔗 Connect and integrate to your data lake (S3, Snowflake, Databricks)

## Step-by-step guide

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title="Submit a POST request"><p>Make a <strong class="slate-bold">POST</strong> request with a JSON body — either inline or attached as a file using <strong class="slate-bold">multipart/form-data</strong>.</p></Step>
<Step stepNumber="2" title="Track your report"><p>After you receive your <strong class="slate-bold">report ID</strong>, use the Request Report Status endpoint to receive the status and download URL once the report is ready.</p></Step>
</Steps>

<Tabs attributes='{"style":{"width":"100%"},"isFitToPage":true,"tabs":["POST","Python"]}'>
<TabPanel tabTitle="POST">
**POST** `https://api.similarweb.com/batch/v4/request-report`
</TabPanel>
<TabPanel tabTitle="Python">
<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"python","label":"Python"}'>
  <CodeLine>import requests

url = "https://api.similarweb.com/batch/v4/request-report"

payload = {}
files = [
  ('request', ('Batchexample.json', open('/Users/Batchexample.json', 'rb'), 'application/json'))
]
headers = {
  'api-key': '{{your_api_key}}'
}

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

print(response.text)</CodeLine>
</CodeBlock>
</TabPanel>
</Tabs>

### Example JSON body

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"Request Body"}'>
  <CodeLine>{
  "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"
      }
    ]
  }
}</CodeLine>
</CodeBlock>

## Mandatory parameters

When requesting a report, include the following parameters in your JSON body.

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"setup-col1","title":"Parameter"},{"id":"setup-col2","title":"Description"},{"id":"setup-col3","title":"Acceptable values"}]'>
  <table-row>
    <table-cell>vtable</table-cell>
    <table-cell>The dataset you want to pull metrics from. See the full list on Datahub or the discovery endpoints.</table-cell>
    <table-cell>traffic_and_engagement</table-cell>
  </table-row>
  <table-row>
    <table-cell>domains</table-cell>
    <table-cell>Domain names may include letters, numbers, dashes, and hyphens. One request supports up to 1M domains.</table-cell>
    <table-cell>amazon.com</table-cell>
  </table-row>
  <table-row>
    <table-cell>countries</table-cell>
    <table-cell>2-letter ISO country codes (case-sensitive, capital letters). Use "WW" for worldwide. When calling desktop_top_geo, remove all countries from your JSON.</table-cell>
    <table-cell>WW, US, GB</table-cell>
  </table-row>
  <table-row>
    <table-cell>metrics</table-cell>
    <table-cell>List of metrics per dataset.</table-cell>
    <table-cell>all_traffic_visits</table-cell>
  </table-row>
  <table-row>
    <table-cell>start_date, end_date</table-cell>
    <table-cell>Daily granularity uses YYYY-MM-DD; monthly granularity uses YYYY-MM.</table-cell>
    <table-cell>Daily: 2023-06-30 / Monthly: 2023-06</table-cell>
  </table-row>
  <table-row>
    <table-cell>granularity</table-cell>
    <table-cell>Time series granularity.</table-cell>
    <table-cell>monthly, weekly, daily</table-cell>
  </table-row>
  <table-row>
    <table-cell>response_format</table-cell>
    <table-cell>Output format of the API call.</table-cell>
    <table-cell>JSON, csv, parquet, orc</table-cell>
  </table-row>
</Table>

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Save the report ID</strong> you receive after your API request — you'll need it to track the report status.</p>
  <p>The request limit is 20 pending requests per user. If you receive a <strong class="slate-bold">429</strong> error, you've exceeded the limit. Reduce the frequency of your requests to stay within your account limits.</p>
</Callout>

## Optional parameters

<Table style="width:100%;min-width:100%" colSizes='["initial","initial","initial"]' isHeaderAdded='true' tableHeader='[{"id":"opt-col1","title":"Parameter"},{"id":"opt-col2","title":"Description"},{"id":"opt-col3","title":"Acceptable values"}]'>
  <table-row>
    <table-cell>delivery_method</table-cell>
    <table-cell>Default is "download_link". When set to "snowflake", the response_format field is not required.</table-cell>
    <table-cell>download_link, bucket_access, snowflake</table-cell>
  </table-row>
  <table-row>
    <table-cell>delivery_method_params</table-cell>
    <table-cell>Use when delivering reports to aggregated Snowflake tables. Input "table_name": "your_table_name".</table-cell>
    <table-cell>table_name, integration_name, retention_days, overwrite_partitions</table-cell>
  </table-row>
  <table-row>
    <table-cell>all_history</table-cell>
    <table-cell>When true, automatically overrides dates to the minimum start and maximum end dates.</table-cell>
    <table-cell>true / false</table-cell>
  </table-row>
  <table-row>
    <table-cell>latest</table-cell>
    <table-cell>When true, overrides the end date with the latest available date.</table-cell>
    <table-cell>true / false</table-cell>
  </table-row>
  <table-row>
    <table-cell>window_size</table-cell>
    <table-cell>Overrides the start date with a time relative to the end date.</table-cell>
    <table-cell>{number}{y/m/d} — e.g. 12d, 3m, 2y</table-cell>
  </table-row>
  <table-row>
    <table-cell>limit</table-cell>
    <table-cell>Limits the number of results per entity selected.</table-cell>
    <table-cell>Above 0; default is 100 for most metrics</table-cell>
  </table-row>
  <table-row>
    <table-cell>include_subdomains</table-cell>
    <table-cell>Default is true.</table-cell>
    <table-cell>true / false</table-cell>
  </table-row>
  <table-row>
    <table-cell>webhook_url</table-cell>
    <table-cell>Delivery URL we'll ping when the status of your report changes.</table-cell>
    <table-cell>URL</table-cell>
  </table-row>
  <table-row>
    <table-cell>sort</table-cell>
    <table-cell>Sort by a specific metric.</table-cell>
    <table-cell>"sort": "all_traffic_visits"</table-cell>
  </table-row>
</Table>

## Get the report status

After submitting a request and receiving your report ID, use the Request Report Status endpoint to check progress.

<Tabs attributes='{"style":{"width":"100%"},"isFitToPage":true,"tabs":["GET","Python"]}'>
<TabPanel tabTitle="GET">
**GET** `https://api.similarweb.com/v3/batch/request-status/{{generated_report_id}}`
</TabPanel>
<TabPanel tabTitle="Python">
<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"python","label":"Python"}'>
  <CodeLine>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)</CodeLine>
</CodeBlock>
</TabPanel>
</Tabs>

### Example responses

<Tabs attributes='{"style":{"width":"100%"},"isFitToPage":true,"tabs":["Completed","In Progress"]}'>
<TabPanel tabTitle="Completed">
<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"Completed Report"}'>
  <CodeLine>{
  "data_points_count": 1779429,
  "download_url": "example_url.com",
  "status": "completed",
  "used_quota": 35589
}</CodeLine>
</CodeBlock>
</TabPanel>
<TabPanel tabTitle="In Progress">
<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"In Progress"}'>
  <CodeLine>{
  "status": "pending"
}</CodeLine>
</CodeBlock>
</TabPanel>
</Tabs>

## Data credits per request

<Callout attributes='{"isFitToPage":true,"dataType":"success","style":{"width":"100%","minWidth":"100%"}}'>
  <p>The download link remains valid for <strong class="slate-bold">30 days</strong>. We recommend saving it for some time in case you need our help troubleshooting any issue.</p>
</Callout>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Data credits are calculated for each report based on the number of results you are actually receiving:</p>
  <p><strong class="slate-bold">Formula:</strong> Number of <strong class="slate-bold">domains</strong> × Number of <strong class="slate-bold">metrics</strong> × <strong class="slate-bold">history</strong> × <strong class="slate-bold">cadence</strong> (daily/monthly) × Number of <strong class="slate-bold">countries</strong> × Number of <strong class="slate-bold">results</strong></p>
</Callout>

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>In order to calculate the estimated credits the report will cost, you can use the "request-validate" endpoint:</p>
  <p><a href="https://api.similarweb.com/v3/batch/request-validate" target="_blank">https://api.similarweb.com/v3/batch/request-validate</a></p>
</Callout>


Set up your Batch API

The discovery endpoints help you understand what's available before you submit a report. Use them to describe the available virtual tables, validate your webhook URL, and check your remaining account or user credits — all free of charge and without consuming your quota.


Batch API - Discovery

The Similarweb Batch API supports a range of datasets covering websites, audience and demographics, search and on-site search, apps, companies, technologies, ecommerce, and conversion analysis. Each dataset has its own dedicated page below with available metrics, filters, and sample requests.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>You can view the full list of datasets on <a href="https://dash.readme.com/go/similarweb?redirect=%2Fv4.0%2Fdocs%2Fdatahub" target="_blank">Datahub</a> or by calling the Describe Available Tables discovery endpoint.</p>
</Callout>


Batch API - Datasets

Batch API - Integrations

**Webhooks in Similarweb: Real-Time Notifications for Your Data Needs**

Webhooks let you stay informed about events and updates from the Similarweb API in real time. By subscribing to webhook notifications, your applications and systems are always up to date with the latest insights without the need for constant polling.

## Introduction to webhooks

Webhooks are a mechanism for receiving real-time notifications when specific events occur within the Similarweb API. Instead of repeatedly querying the API for updates, webhooks let Similarweb send POST requests directly to your endpoints as soon as an event of interest takes place.

*   **Real-time updates** — Know immediately when your report is available to download.
*   **Automations** — Build automations around your reporting and dashboards.

## Setting up webhooks

<Steps attributes='{"style":{"width":"100%","minWidth":"100%"}}'>
<Step stepNumber="1" title="Configure your endpoint"><p>Create a URL in your application that can receive HTTP POST requests from Similarweb.</p></Step>
<Step stepNumber="2" title="Validate using the webhook test endpoint"><p>Use the Check Webhook endpoint to validate that your webhook integration is successful.</p></Step>
<Step stepNumber="3" title="Use your validated URL with report endpoints"><p>Once validated, include the <strong class="slate-bold">webhook_url</strong> field in your report request body.</p></Step>
</Steps>

### Test webhook request

<Tabs attributes='{"style":{"width":"100%"},"isFitToPage":true,"tabs":["POST","Python"]}'>
<TabPanel tabTitle="POST">
<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"bash","label":"POST"}'>
  <CodeLine>POST https://api.similarweb.com/v3/batch/webhooks/test

{
  "webhook_url": "http://slack.com/example_url/abc"
}</CodeLine>
</CodeBlock>
</TabPanel>
<TabPanel tabTitle="Python">
<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"python","label":"Python"}'>
  <CodeLine>import requests

url = "https://api.similarweb.com/v3/batch/webhooks/test"

payload = "{\n\"webhook_url\": \"http://slack.com/example_url/abc\"\n}"
headers = {
  'api-key': '{{api_key}}'
}

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

print(response.text)</CodeLine>
</CodeBlock>
</TabPanel>
</Tabs>

The notification performs a POST with the following body:

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"Test webhook output"}'>
  <CodeLine>{
  "event_type": "test_webhook_endpoint",
  "payload": "Webhook Integration with Similarweb is successful!"
}</CodeLine>
</CodeBlock>

Confirm in your internal system that you've received the `test_webhook_endpoint` event — it should be invoked immediately.

<Callout attributes='{"isFitToPage":true,"dataType":"warning","style":{"width":"100%","minWidth":"100%"}}'>
  <p>Timeout occurs after 5 seconds; a timeout will cause failure.</p>
</Callout>

## Use the validated URL with report endpoints

<CodeBlock attributes='{"isFitToPage":true,"style":{},"lang":"json","label":"POST request-report"}'>
  <CodeLine>POST https://api.similarweb.com/batch/v4/request-report

{
  "webhook_url": "http://slack.com/example_url/abc",
  "domains": ["amazon.com"],
  "category_ids": [2335752011],
  "metrics": [
    "category_sales_performance_product_views",
    "category_sales_performance_units_sold",
    "category_sales_performance_revenue",
    "category_sales_performance_cvr"
  ],
  "start_date": "2021-09",
  "end_date": "2021-11",
  "granularity": "monthly",
  "response_format": "csv"
}</CodeLine>
</CodeBlock>

When the report status changes, the webhook is triggered.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p><strong class="slate-bold">Possible Report Statuses:</strong> "processing", "complete", or "internal_error".</p>
</Callout>


Webhook Endpoints

Similarweb MCP

MCP Integrations

Support and FAQ

Country Codes

Check Capabilities

Default

API V5 latest - USE THIS

Similarweb API V5 Documentation

Production

Sandbox

Ad Networks

AI Outreach

Amazon S3 Integration

App Active Users (DAU/WAU/MAU)

App Cross-Usage & Affinity

App Demographics

App Details

App Downloads

App IAB Categories

App Install Penetration

App Ranks

App Retention

App Revenue

App Search

App Sessions

App Technographics (SDKs)

App Top Charts

Contacts

Contacts Enrichment - Single

Contacts Enrichment - Bulk

Contacts Search

Lead Enrichment

Lead Enrichment - Company

Lead Enrichment - Website

Prompt Tracking

Keyword Competitors

Keywords Overview

Landing Pages

SERP Players - Aggregated

SERP Players - Clicks over time

Website Keywords

Website Audience

Audience Interest

Audience Overlap

Deduplicated Audience

Demographics

Demographics - specific groups

Website Content

Popular pages

Website Folders

Website Subdomains

Website Technologies

Website Performance

Conversion Rates Aggregated

Conversion Rates Over Time

Marketing Channel Sources

PPC Spend

Referrals

Top Sites Ranking

Traffic & Engagement

Traffic Geography

Website Ranking

Website Segments

List predefined segments

List User Segments

Segments Analysis

Segments Marketing Channels

App Technographics - Supported SDKs

Apps Dataset

How to find App IDs?

Company Dataset

Conversion Analysis (Site level) - All Traffic

Ecommerce Dataset (Shopper Intent)

Set Up Shopper Intelligence API

Intro to the Batch API Datasets

On-Site Search Dataset

Search Dataset

Technologies Dataset

Websites Audience & Demographics Dataset

Websites Dataset

Describe Available Tables (GET)

Get Remaining Credits (GET)

Get Remaining User Credits (GET)

Renew S3 Integration (POST)

Revoke S3 Integration (POST)

Revoke S3 Table (POST)

S3 Integration (POST)

Get All Account Integrations (GET)

Google Cloud Storage Integration

Renew GCS Integration (POST)

Revoke GCS Integration (POST)

Revoke GCS Table (POST)

Salesforce Connector

Snowflake API Integration

Get All Snowflake Integration Tables (GET)

Revoke Snowflake Integration (POST)

Snowflake Integration (POST)

Report Endpoints

Test Your Webhooks (GET)

Batch API - Geography from REST

Batch API - Referrals from REST

Batch API Request - Step-by-Step Walkthrough

ChatGPT MCP Integration

Check Data Credits Balance

Claude MCP Integration

Cursor MCP Integration

Recipes

Snowflake Table Integration

S3 Table Integration

GCS Table Integration

Batch API - Segment from REST

Batch API - Traffic and Engagement from REST

Batch API - Keywords from REST

Manus MCP Integration

Microsoft Copilot MCP Integration

Perplexity MCP Integration

This endpoint provides a comprehensive list of all available tables that can be queried using the Batch API. It is the key resource for understanding what data can be extracted via the `request-report` endpoint.


This endpoint returns your current remaining account credits.


This endpoint returns your current remaining user credits.

<Callout attributes='{"isFitToPage":true,"dataType":"info","style":{"width":"100%","minWidth":"100%"}}'>
  <p>This endpoint is relevant only if the requesting user has a credits limitation set. If a limitation is not set, both <code>user_allowance</code> and <code>user_remaining</code> return as <code>null</code> — in that case, refer to the <strong class="slate-bold">Get Remaining Credits</strong> endpoint instead.</p>
</Callout>


<p class="slate-p " >The discovery endpoints help you understand what&apos;s available before you submit a report. Use them to describe the available virtual tables, validate your webhook URL, and check your remaining account or user credits — all free of charge and without consuming your quota.</p><p class="slate-p " ></p>

The discovery endpoints help you understand what's available before you submit a report. Use them to describe the available virtual tables, validate your webhook URL, and check your remaining account or user credits — all free of charge and without consuming your quota.

Sections

Batch API - Discovery

On this page

Sections

Batch API - Discovery

On this page

Ask an AI

Code with AI