Introduction

Note

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:

count

The total number of events over the specified time period.

Example response:

{  "clicks": 100,  "leads": 5,  "sales": 2,  "saleAmount": 5000}

timeseries

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

top_links

The top links by event count, including link metadata.

Example response:

[  {    "id": "clux0rgak00011...",    "domain": "dub.co",    "key": "github",    "shortLink": "https://dub.co/github",    "url": "https://github.com",    "title": "GitHub",    "createdAt": "2024-01-01T00:00:00.000Z",    "clicks": 50,    "leads": 3,    "sales": 1,    "saleAmount": 2500  }]

countries

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

cities

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

regions

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

continents

The top continents by event count, using 2-letter ISO continent codes.

Example response:

[  {    "continent": "NA",    "clicks": 40,    "leads": 3,    "sales": 2,    "saleAmount": 5000  }]

devices

The top devices by event count, including device names.

Example response:

[  {    "device": "iPhone",    "clicks": 35,    "leads": 2,    "sales": 1,    "saleAmount": 2500  }]

browsers

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

referrers

The top referrers by event count, including referrer names.

Example response:

[  {    "referer": "Google",    "clicks": 25,    "leads": 2,    "sales": 1,    "saleAmount": 2500  }]

referer_urls

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

utm_sources

The top UTM sources by event count.

Example response:

[  {    "utm_source": "newsletter",    "clicks": 25,    "leads": 2,    "sales": 1,    "saleAmount": 2500  }]

utm_mediums

The top UTM mediums by event count.

Example response:

[  {    "utm_medium": "email",    "clicks": 20,    "leads": 1,    "sales": 1,    "saleAmount": 2500  }]

utm_campaigns

The top UTM campaigns by event count.

Example response:

[  {    "utm_campaign": "summer_sale",    "clicks": 30,    "leads": 2,    "sales": 1,    "saleAmount": 2500  }]

utm_terms

The top UTM terms by event count.

Example response:

[  {    "utm_term": "discount",    "clicks": 15,    "leads": 1,    "sales": 1,    "saleAmount": 2500  }]

utm_contents

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
Timeseries data
Top links by event

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",});