List Events

Endpoint

https://api.dub.co/events

Authentication

This endpoint requires authentication using a Bearer token.

Authorization

string

required

Bearer token for authentication

This endpoint requires a Business plan or higher.

Query Parameters

Event Configuration

event

enum

default:"clicks"

required

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

Show Example

event=leads

Pagination

page

number

default:1

The page number for pagination. Defaults to 1.

Show Example

page=2

limit

number

default:50

The number of events to return per page. Max 1000 items per page.

Show Example

limit=100

Sorting

sortBy

enum

default:"timestamp"

The field to sort the events by. The default is timestamp.Options: timestamp

Show Example

sortBy=timestamp

sortOrder

enum

default:"desc"

The sort order. The default is desc.Options: asc, desc

Show Example

sortOrder=asc

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.

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.

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.

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. 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.

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

Returns an array of event objects. The structure of each event depends on the event type:

Click Event

event

string

The event type: click

timestamp

string

The timestamp of the event in ISO 8601 format

click

object

The click event details

Show properties

string

The unique ID of the click event

url

string

The destination URL

country

string

The 2-letter ISO 3166-1 country code

city

string

The city name

region

string

The 2-letter ISO 3166-2 region code

continent

string

The 2-letter continent code

device

string

The device type (e.g., Desktop, Mobile, Tablet)

browser

string

The browser name

string

The operating system name

referer

string

The referer hostname

refererUrl

string

The full referer URL

boolean

Whether the click was from a QR code scan

string

The IP address of the user

link

object

The link details

Show properties

string

The unique ID of the link

domain

string

The domain of the short link

key

string

The key/slug of the short link

url

string

The destination URL

externalId

string

The external ID of the link in your system

programId

string

The ID of the program the link is associated with

tenantId

string

The tenant ID of the link

Lead Event

event

string

The event type: lead

timestamp

string

The timestamp of the event in ISO 8601 format

eventId

string

The unique ID of the lead event

eventName

string

The name of the lead event (e.g., “Sign up”)

metadata

object

Additional metadata stored with the lead event

click

object

The click event details (same structure as Click Event above)

link

object

The link details (same structure as Click Event above)

customer

object

The customer details

Show properties

string

The unique ID of the customer

name

string

Name of the customer

string

Email of the customer

avatar

string

Avatar URL of the customer

externalId

string

Unique identifier for the customer in your system

country

string

Country of the customer

Sale Event

event

string

The event type: sale

timestamp

string

The timestamp of the event in ISO 8601 format

eventId

string

The unique ID of the sale event

eventName

string

The name of the sale event (e.g., “Invoice paid”)

sale

object

The sale details

Show properties

amount

number

The amount of the sale in cents

invoiceId

string

The invoice ID of the sale

paymentProcessor

string

The payment processor (e.g., stripe, shopify, paddle)

metadata

object

Additional metadata stored with the sale event

click

object

The click event details (same structure as Click Event above)

link

object

The link details (same structure as Click Event above)

customer

object

The customer details (same structure as Lead Event above)

Examples

curl -X GET "https://api.dub.co/events?event=clicks&limit=100&sortOrder=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Examples

[
  {
    "event": "click",
    "timestamp": "2024-01-15T14:32:10.000Z",
    "click": {
      "id": "clk_abc123",
      "url": "https://github.com/dubinc/dub",
      "country": "US",
      "city": "New York",
      "region": "NY",
      "continent": "NA",
      "device": "Desktop",
      "browser": "Chrome",
      "os": "Mac",
      "referer": "google.com",
      "refererUrl": "https://google.com/search?q=dub",
      "qr": false,
      "ip": "192.168.1.1"
    },
    "link": {
      "id": "clux0rgak00011...",
      "domain": "dub.co",
      "key": "github",
      "url": "https://github.com/dubinc/dub",
      "externalId": "123456",
      "programId": null,
      "tenantId": null
    }
  }
]

Overview

Links

Analytics

Events

Domains

Tags

Folders

Tracking

Customers

QR Codes

List Events

Endpoint

Authentication

Query Parameters

Event Configuration

Sorting

Link Identification

Time Range

Filtering

Geographic Filters

Device & Browser Filters

Traffic Source Filters

UTM Parameters

Other Filters

Response

Click Event

Lead Event

Sale Event

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

​Pagination

​Sorting

​Link Identification

​Time Range

​Filtering

​Geographic Filters

​Device & Browser Filters

​Traffic Source Filters

​UTM Parameters

​Other Filters

​Response

​Click Event

​Lead Event

​Sale Event

​Examples

​Response Examples

Build docs developers (and LLMs) love

Endpoint

Authentication

Query Parameters

Event Configuration

Pagination

Sorting

Link Identification

Time Range

Filtering

Geographic Filters

Device & Browser Filters

Traffic Source Filters

UTM Parameters

Other Filters

Response

Click Event

Lead Event

Sale Event

Examples

Response Examples