Retrieve Analytics

Endpoint

https://api.dub.co/analytics

Authentication

This endpoint requires authentication using a Bearer token.

Authorization

string

required

Bearer token for authentication

Query Parameters

Event Configuration

event

enum

default:"clicks"

The type of event to retrieve analytics for. Defaults to clicks.Options: clicks, leads, sales, composite

Show Example

event=leads

groupBy

enum

default:"count"

The parameter to group the analytics data points by. Defaults to count if undefined.Options: count, timeseries, continents, countries, regions, cities, devices, browsers, os, triggers, referers, referer_urls, top_links, top_urls

Show Example

groupBy=countries

Link Identification

domain

string

The domain to filter analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

Show Examples

domain=dub.co
domain=dub.co,google.com
domain=-spam.com

key

string

The slug of the short link to retrieve analytics for. Must be used along with the corresponding domain of the short link to fetch analytics for a specific short link.

Show Example

domain=dub.co&key=github

linkId

string

The unique ID of the link to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

Show Examples

linkId=link_123
linkId=link_123,link_456
linkId=-link_789

externalId

string

The ID of the link in your database. Must be prefixed with ‘ext_’ when passed as a query parameter.

Show Example

externalId=ext_123456

Time Range

interval

enum

The interval to retrieve analytics for. If undefined, defaults to 24h.Options: 1h, 24h, 7d, 30d, 90d, ytd, 1y, all, all_unfiltered

Show Example

interval=7d

start

string

The start date and time when to retrieve analytics from. If set, takes precedence over interval. Format: ISO 8601 date string.

Show Example

start=2024-01-01T00:00:00Z

end

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with start, takes precedence over interval.

Show Example

end=2024-12-31T23:59:59Z

timezone

string

default:"UTC"

The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.

Show Example

timezone=America/New_York

Filtering

tenantId

string

The ID of the tenant that created the link inside your system. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

Show Examples

tenantId=tenant_123
tenantId=tenant_123,tenant_456
tenantId=-tenant_789

tagId

string

The tag ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

Show Examples

tagId=tag_123
tagId=tag_123,tag_456
tagId=-tag_789

folderId

string

The folder ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). If not provided, return analytics for all links.

Show Examples

folderId=folder_123
folderId=folder_123,folder_456
folderId=-folder_789

groupId

string

The group ID to retrieve analytics for. Supports advanced filtering.

Show Examples

groupId=grp_123
groupId=grp_123,grp_456
groupId=-grp_789

partnerId

string

The ID of the partner to retrieve analytics for. Supports advanced filtering.

Show Examples

partnerId=pn_123
partnerId=pn_123,pn_456
partnerId=-pn_789

customerId

string

The ID of the customer to retrieve analytics for.

Show Example

customerId=cus_123

Geographic Filters

country

string

The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

Show Examples

country=US
country=US,BR,FR
country=-US

city

string

The city to retrieve analytics for. Supports advanced filtering.

Show Examples

city=New York
city=New York,London
city=-New York

region

string

The ISO 3166-2 region code to retrieve analytics for. Supports advanced filtering.

Show Examples

region=NY
region=NY,CA
region=-NY

continent

string

The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. Supports advanced filtering.

Show Examples

continent=NA
continent=NA,EU
continent=-AS

Device & Browser Filters

device

string

The device to retrieve analytics for. Supports advanced filtering.

Show Examples

device=Desktop
device=Mobile,Tablet
device=-Mobile

browser

string

The browser to retrieve analytics for. Supports advanced filtering.

Show Examples

browser=Chrome
browser=Chrome,Firefox,Safari
browser=-IE

string

The OS to retrieve analytics for. Supports advanced filtering.

Show Examples

os=Windows
os=Mac,Windows,Linux
os=-Windows

Traffic Source Filters

trigger

string

The trigger to retrieve analytics for. Valid values: qr, link, pageview. Supports advanced filtering. If undefined, returns all trigger types.

Show Examples

trigger=qr
trigger=qr,link
trigger=-qr

referer

string

The referer hostname to retrieve analytics for. Supports advanced filtering.

Show Examples

referer=google.com
referer=google.com,twitter.com
referer=-facebook.com

refererUrl

string

The full referer URL to retrieve analytics for. Supports advanced filtering.

Show Examples

refererUrl=https://google.com
refererUrl=https://google.com,https://twitter.com
refererUrl=-https://spam.com

UTM Parameters

utm_source

string

The UTM source to retrieve analytics for. Supports advanced filtering.

Show Examples

utm_source=google
utm_source=google,twitter
utm_source=-spam

utm_medium

string

The UTM medium to retrieve analytics for. Supports advanced filtering.

Show Examples

utm_medium=cpc
utm_medium=cpc,social
utm_medium=-email

utm_campaign

string

The UTM campaign to retrieve analytics for. Supports advanced filtering.

Show Examples

utm_campaign=summer_sale
utm_campaign=summer_sale,winter_sale
utm_campaign=-old_campaign

utm_term

string

The UTM term to retrieve analytics for. Supports advanced filtering.

utm_content

string

The UTM content to retrieve analytics for. Supports advanced filtering.

Other Filters

url

string

The destination URL to retrieve analytics for. Supports advanced filtering.

Show Examples

url=https://example.com
url=https://example.com,https://other.com
url=-https://spam.com

root

boolean

Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.

saleType

enum

Filter sales by type: ‘new’ for first-time purchases, ‘recurring’ for repeat purchases. If undefined, returns both.Options: new, recurring

query

string

Search the events by a custom metadata value. Only available for lead and sale events. Max 10,000 characters.

Show Example

query=metadata['key']:'value'

Response

The response varies based on the groupBy parameter:

Count Analytics

clicks

number

default:0

The total number of clicks

leads

number

default:0

The total number of leads

sales

number

default:0

The total number of sales

saleAmount

number

default:0

The total amount of sales, in cents

Timeseries Analytics

Returns an array of time-series data points:

start

string

The starting timestamp of the interval

clicks

number

default:0

The number of clicks in the interval

leads

number

default:0

The number of leads in the interval

sales

number

default:0

The number of sales in the interval

saleAmount

number

default:0

The total amount of sales in the interval, in cents

Geographic Analytics

Returns an array of geographic data points (countries, regions, cities, or continents):

country

string

The 2-letter ISO 3166-1 country code (for countries, regions, cities)

continent

string

The 2-letter ISO 3166-1 continent code (for continents)

region

string

The 2-letter ISO 3166-2 region code (for regions, cities)

city

string

The name of the city (for cities)

clicks

number

default:0

The number of clicks from this location

leads

number

default:0

The number of leads from this location

sales

number

default:0

The number of sales from this location

saleAmount

number

default:0

The total amount of sales from this location, in cents

Device Analytics

Returns an array of device, browser, or OS data:

device

string

The name of the device (for devices groupBy)

browser

string

The name of the browser (for browsers groupBy)

string

The name of the OS (for os groupBy)

clicks

number

default:0

The number of clicks

leads

number

default:0

The number of leads

sales

number

default:0

The number of sales

saleAmount

number

default:0

The total amount of sales, in cents

Trigger Analytics

Returns an array of trigger methods:

trigger

enum

The type of trigger method: link click or QR scan

clicks

number

default:0

The number of clicks from this trigger method

leads

number

default:0

The number of leads from this trigger method

sales

number

default:0

The number of sales from this trigger method

saleAmount

number

default:0

The total amount of sales from this trigger method, in cents

Referer Analytics

Returns an array of referer data:

referer

string

The name of the referer. If unknown, this will be (direct) (for referers groupBy)

refererUrl

string

The full URL of the referer. If unknown, this will be (direct) (for referer_urls groupBy)

clicks

number

default:0

The number of clicks from this referer

leads

number

default:0

The number of leads from this referer

sales

number

default:0

The number of sales from this referer

saleAmount

number

default:0

The total amount of sales from this referer, in cents

Top URLs Analytics

Returns an array of top destination URLs:

url

string

The full destination URL (including query parameters)

clicks

number

default:0

The number of clicks from this URL

leads

number

default:0

The number of leads from this URL

sales

number

default:0

The number of sales from this URL

saleAmount

number

default:0

The total amount of sales from this URL, in cents

Examples

curl -X GET "https://api.dub.co/analytics?event=clicks&groupBy=count&interval=7d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

{
  "clicks": 1234,
  "leads": 45,
  "sales": 12,
  "saleAmount": 567800
}

Overview

Links

Analytics

Events

Domains

Tags

Folders

Tracking

Customers

QR Codes

Retrieve Analytics

Endpoint

Authentication

Query Parameters

Event Configuration

Link Identification

Time Range

Filtering

Geographic Filters

Device & Browser Filters

Traffic Source Filters

UTM Parameters

Other Filters

Response

Count Analytics

Timeseries Analytics

Geographic Analytics

Device Analytics

Trigger Analytics

Referer Analytics

Top Links Analytics

Top URLs Analytics

Examples

Response Examples

Build docs developers (and LLMs) love

Overview

Links

Analytics

Events

Domains

Tags

Folders

Tracking

Customers

QR Codes

​Endpoint

​Authentication

​Query Parameters

​Event Configuration

​Link Identification

​Time Range

​Filtering

​Geographic Filters

​Device & Browser Filters

​Traffic Source Filters

​UTM Parameters

​Other Filters

​Response

​Count Analytics

​Timeseries Analytics

​Geographic Analytics

​Device Analytics

​Trigger Analytics

​Referer Analytics

​Top Links Analytics

​Top URLs Analytics

​Examples

​Response Examples

Build docs developers (and LLMs) love

Endpoint

Authentication

Query Parameters

Event Configuration

Link Identification

Time Range

Filtering

Geographic Filters

Device & Browser Filters

Traffic Source Filters

UTM Parameters

Other Filters

Response

Count Analytics

Timeseries Analytics

Geographic Analytics

Device Analytics

Trigger Analytics

Referer Analytics

Top Links Analytics

Top URLs Analytics

Examples

Response Examples