Skip to main content
Analytics endpoints require a Pro plan subscription or higher.
Dub’s Analytics API allows you to build real-time analytics dashboards for your links that lives directly inside your application.

​
Fundamentals

At a high level, Dub’s Analytics API allows you to retrieve data about your links by event type and group by different dimensions. Dub’s Analytics API supports the following event types:
  • clicks – the number of clicks on a link
  • leads – the number of leads generated from a link
  • sales – the number of sales generated from a link
Each of these events can be aggregated in different ways by using the groupBy parameter:
The total number of events over the specified time period.Example response:
{
  "clicks": 100,
  "leads": 5,
  "sales": 2,
  "saleAmount": 5000
}
The number of events over a given time interval, broken down by time periods.Example response:
[
  {
    "start": "2024-01-01T00:00:00.000Z",
    "clicks": 10,
    "leads": 1,
    "sales": 0,
    "saleAmount": 0
  },
  {
    "start": "2024-01-02T00:00:00.000Z",
    "clicks": 15,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top countries by event count, using ISO 3166-1 alpha-2 country codes.Example response:
[
  {
    "country": "US",
    "region": "*",
    "city": "*",
    "clicks": 30,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top cities by event count, including city names and ISO 3166-1 alpha-2 country codes.Example response:
[
  {
    "country": "US",
    "region": "CA",
    "city": "San Francisco",
    "clicks": 20,
    "leads": 1,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top regions by event count, including region codes and ISO 3166-1 alpha-2 country codes.Example response:
[
  {
    "country": "US",
    "region": "CA",
    "city": "*",
    "clicks": 25,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top continents by event count, using 2-letter ISO continent codes.Example response:
[
  {
    "continent": "NA",
    "clicks": 40,
    "leads": 3,
    "sales": 2,
    "saleAmount": 5000
  }
]
The top devices by event count, including device names.Example response:
[
  {
    "device": "iPhone",
    "clicks": 35,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top browsers by event count, including browser names.Example response:
[
  {
    "browser": "Chrome",
    "clicks": 45,
    "leads": 3,
    "sales": 2,
    "saleAmount": 5000
  }
]
The top operating systems by event count, including OS names.Example response:
[
  {
    "os": "iOS",
    "clicks": 30,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top referrers by event count, including referrer names.Example response:
[
  {
    "referer": "Google",
    "clicks": 25,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top referrer URLs by event count, including full URLs.Example response:
[
  {
    "refererUrl": "https://www.google.com",
    "clicks": 20,
    "leads": 1,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top UTM sources by event count.Example response:
[
  {
    "utm_source": "newsletter",
    "clicks": 25,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top UTM mediums by event count.Example response:
[
  {
    "utm_medium": "email",
    "clicks": 20,
    "leads": 1,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top UTM campaigns by event count.Example response:
[
  {
    "utm_campaign": "summer_sale",
    "clicks": 30,
    "leads": 2,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top UTM terms by event count.Example response:
[
  {
    "utm_term": "discount",
    "clicks": 15,
    "leads": 1,
    "sales": 1,
    "saleAmount": 2500
  }
]
The top UTM contents by event count.Example response:
[
  {
    "utm_content": "banner",
    "clicks": 20,
    "leads": 1,
    "sales": 1,
    "saleAmount": 2500
  }
]

​
Example queries

Here are some examples of how to retrieve data using Dub’s Analytics API:

​
Total event count

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const result = await dub.analytics.retrieve({
  event: "clicks",
  groupBy: "count",
  linkId: "clux0rgak00011...",
  interval: "30d",
});

​
Timeseries data

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const result = await dub.analytics.retrieve({
  event: "clicks",
  groupBy: "timeseries",
  linkId: "clux0rgak00011...",
  interval: "30d",
});

import { Dub } from "dub";

export const dub = new Dub({
  token: process.env.DUB_API_KEY,
});

const result = await dub.analytics.retrieve({
  event: "clicks",
  groupBy: "top_links",
  linkId: "clux0rgak00011...",
  interval: "30d",
});

​
Example apps

With Dub’s Analytics API, you can build user-facing analytics dashboards with the real-time click and conversion data for your links. Here are some open-source examples of how you can use the Analytics API to build your own custom analytics dashboards:

OSS Gallery

Programmatically shorten links and fetch real-time click analytics with Dub

Cap.so

How Cap.so fetches real-time click analytics for their recording links
And here’s another real-world example of a custom analytics dashboard built with the Analytics API:
Assembly link analytics
⌘I