Retrieve a list of events

Retrieve a paginated list of events for the authenticated workspace.

Events endpoints require a Business plan subscription or higher.

Authorizations

Authorization

string

headerrequired

Default authentication mechanism

Query Parameters

event

enum<string>

default: clicks

The type of event to retrieve analytics for. Defaults to 'clicks'.

Available options:

clicks,

leads,

sales

domain

string

The domain to filter analytics for.

key

string

The short link slug.

linkId

string

The unique ID of the short link on Dub.

externalId

string

This is the ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.

interval

enum<string>

default: 24h

The interval to retrieve events for. Takes precedence over start and end. If undefined, defaults to 24h.

Available options:

24h,

7d,

30d,

90d,

ytd,

1y,

all

start

string

The start date and time when to retrieve analytics from. Takes precedence over interval.

end

string

The end date and time when to retrieve analytics from. If not provided, defaults to the current date. Takes precedence over interval.

timezone

string

default: UTC

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

country

enum<string>

The country to retrieve analytics for.

Available options:

AF,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

KH,

CM,

CA,

CV,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

CI,

HR,

CU,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IL,

IT,

JM,

JP,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MK,

MP,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

SH,

KN,

LC,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

SC,

SL,

SG,

SK,

SI,

SB,

SO,

ZA,

GS,

ES,

LK,

SD,

SR,

SJ,

SZ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

US,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

AX,

BQ,

CW,

GG,

IM,

JE,

ME,

BL,

MF,

RS,

SX,

SS,

XK

city

string

The city to retrieve analytics for.

region

string

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

continent

enum<string>

The continent to retrieve analytics for.

Available options:

AF,

AN,

AS,

EU,

NA,

OC,

SA

device

string

The device to retrieve analytics for.

browser

string

The browser to retrieve analytics for.

os

string

The OS to retrieve analytics for.

trigger

enum<string>

The trigger to retrieve analytics for. If undefined, return both QR and link clicks.

Available options:

qr,

link

referer

string

The referer to retrieve analytics for.

refererUrl

string

The full referer URL to retrieve analytics for.

url

string

The URL to retrieve analytics for.

tagId

string

deprecated

Deprecated. Use tagIds instead. The tag ID to retrieve analytics for.

tagIds

The tag IDs to retrieve analytics for.

qr

boolean

deprecated

Deprecated. Use the trigger field instead. Filter for QR code scans. If true, filter for QR codes only. If false, filter for links only. If undefined, return both.

root

boolean

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

page

number

default: 1

limit

number

default: 100

order

enum<string>

default: desc

Available options:

asc,

desc

sortBy

enum<string>

default: timestamp

Available options:

timestamp

Response

200 - application/json

• ClickEvents
• LeadEvents
• SaleEvents

event

enum<string>

required

Available options:

click

timestamp

string

click

object

required

Show child attributes

click.id

string

required

click.url

string

required

click.country

string

required

click.city

string

required

click.region

string

required

click.continent

string

required

click.device

string

required

click.browser

string

required

click.os

string

required

click.referer

string

required

click.refererUrl

string

required

click.ip

string

required

click.qr

boolean

link

object

required

Show child attributes

link.id

string

required

The unique ID of the short link.

link.domain

string

required

The domain of the short link. If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

link.key

string

required

The short link slug. If not provided, a random 7-character slug will be generated.

link.url

string

required

link.externalId

string | null

required

This is the ID of the link in your database that is unique across your workspace. If set, it can be used to identify the link in future API requests. Must be prefixed with 'ext_' when passed as a query parameter.

link.expiresAt

string

required

link.expiredUrl

string | null

required

link.password

string | null

required

The password required to access the destination URL of the short link.

link.title

string | null

required

The title of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

link.description

string | null

required

The description of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

link.image

string | null

required

The image of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

link.video

string | null

required

The custom link preview video (og:video). Will be used for Custom Social Media Cards if proxy is true. Learn more: https://d.to/og

link.ios

string | null

required

The iOS destination URL for the short link for iOS device targeting.

link.android

string | null

required

The Android destination URL for the short link for Android device targeting.

link.geo

object | null

required

Geo targeting information for the short link in JSON format {[COUNTRY]: https://example.com }. Learn more: https://d.to/geo

Show child attributes

link.geo.AF

string

link.geo.AL

string

link.geo.DZ

string

link.geo.AS

string

link.geo.AD

string

link.geo.AO

string

link.geo.AI

string

link.geo.AQ

string

link.geo.AG

string

link.geo.AR

string

link.geo.AM

string

link.geo.AW

string

link.geo.AU

string

link.geo.AT

string

link.geo.AZ

string

link.geo.BS

string

link.geo.BH

string

link.geo.BD

string

link.geo.BB

string

link.geo.BY

string

link.geo.BE

string

link.geo.BZ

string

link.geo.BJ

string

link.geo.BM

string

link.geo.BT

string

link.geo.BO

string

link.geo.BA

string

link.geo.BW

string

link.geo.BV

string

link.geo.BR

string

link.geo.IO

string

link.geo.BN

string

link.geo.BG

string

link.geo.BF

string

link.geo.BI

string

link.geo.KH

string

link.geo.CM

string

link.geo.CA

string

link.geo.CV

string

link.geo.KY

string

link.geo.CF

string

link.geo.TD

string

link.geo.CL

string

link.geo.CN

string

link.geo.CX

string

link.geo.CC

string

link.geo.CO

string

link.geo.KM

string

link.geo.CG

string

link.geo.CD

string

link.geo.CK

string

link.geo.CR

string

link.geo.CI

string

link.geo.HR

string

link.geo.CU

string

link.geo.CY

string

link.geo.CZ

string

link.geo.DK

string

link.geo.DJ

string

link.geo.DM

string

link.geo.DO

string

link.geo.EC

string

link.geo.EG

string

link.geo.SV

string

link.geo.GQ

string

link.geo.ER

string

link.geo.EE

string

link.geo.ET

string

link.geo.FK

string

link.geo.FO

string

link.geo.FJ

string

link.geo.FI

string

link.geo.FR

string

link.geo.GF

string

link.geo.PF

string

link.geo.TF

string

link.geo.GA

string

link.geo.GM

string

link.geo.GE

string

link.geo.DE

string

link.geo.GH

string

link.geo.GI

string

link.geo.GR

string

link.geo.GL

string

link.geo.GD

string

link.geo.GP

string

link.geo.GU

string

link.geo.GT

string

link.geo.GN

string

link.geo.GW

string

link.geo.GY

string

link.geo.HT

string

link.geo.HM

string

link.geo.VA

string

link.geo.HN

string

link.geo.HK

string

link.geo.HU

string

link.geo.IS

string

link.geo.IN

string

link.geo.ID

string

link.geo.IR

string

link.geo.IQ

string

link.geo.IE

string

link.geo.IL

string

link.geo.IT

string

link.geo.JM

string

link.geo.JP

string

link.geo.JO

string

link.geo.KZ

string

link.geo.KE

string

link.geo.KI

string

link.geo.KP

string

link.geo.KR

string

link.geo.KW

string

link.geo.KG

string

link.geo.LA

string

link.geo.LV

string

link.geo.LB

string

link.geo.LS

string

link.geo.LR

string

link.geo.LY

string

link.geo.LI

string

link.geo.LT

string

link.geo.LU

string

link.geo.MO

string

link.geo.MG

string

link.geo.MW

string

link.geo.MY

string

link.geo.MV

string

link.geo.ML

string

link.geo.MT

string

link.geo.MH

string

link.geo.MQ

string

link.geo.MR

string

link.geo.MU

string

link.geo.YT

string

link.geo.MX

string

link.geo.FM

string

link.geo.MD

string

link.geo.MC

string

link.geo.MN

string

link.geo.MS

string

link.geo.MA

string

link.geo.MZ

string

link.geo.MM

string

link.geo.NA

string

link.geo.NR

string

link.geo.NP

string

link.geo.NL

string

link.geo.NC

string

link.geo.NZ

string

link.geo.NI

string

link.geo.NE

string

link.geo.NG

string

link.geo.NU

string

link.geo.NF

string

link.geo.MK

string

link.geo.MP

string

link.geo.NO

string

link.geo.OM

string

link.geo.PK

string

link.geo.PW

string

link.geo.PS

string

link.geo.PA

string

link.geo.PG

string

link.geo.PY

string

link.geo.PE

string

link.geo.PH

string

link.geo.PN

string

link.geo.PL

string

link.geo.PT

string

link.geo.PR

string

link.geo.QA

string

link.geo.RE

string

link.geo.RO

string

link.geo.RU

string

link.geo.RW

string

link.geo.SH

string

link.geo.KN

string

link.geo.LC

string

link.geo.PM

string

link.geo.VC

string

link.geo.WS

string

link.geo.SM

string

link.geo.ST

string

link.geo.SA

string

link.geo.SN

string

link.geo.SC

string

link.geo.SL

string

link.geo.SG

string

link.geo.SK

string

link.geo.SI

string

link.geo.SB

string

link.geo.SO

string

link.geo.ZA

string

link.geo.GS

string

link.geo.ES

string

link.geo.LK

string

link.geo.SD

string

link.geo.SR

string

link.geo.SJ

string

link.geo.SZ

string

link.geo.SE

string

link.geo.CH

string

link.geo.SY

string

link.geo.TW

string

link.geo.TJ

string

link.geo.TZ

string

link.geo.TH

string

link.geo.TL

string

link.geo.TG

string

link.geo.TK

string

link.geo.TO

string

link.geo.TT

string

link.geo.TN

string

link.geo.TR

string

link.geo.TM

string

link.geo.TC

string

link.geo.TV

string

link.geo.UG

string

link.geo.UA

string

link.geo.AE

string

link.geo.GB

string

link.geo.US

string

link.geo.UM

string

link.geo.UY

string

link.geo.UZ

string

link.geo.VU

string

link.geo.VE

string

link.geo.VN

string

link.geo.VG

string

link.geo.VI

string

link.geo.WF

string

link.geo.EH

string

link.geo.YE

string

link.geo.ZM

string

link.geo.ZW

string

link.geo.AX

string

link.geo.BQ

string

link.geo.CW

string

link.geo.GG

string

link.geo.IM

string

link.geo.JE

string

link.geo.ME

string

link.geo.BL

string

link.geo.MF

string

link.geo.RS

string

link.geo.SX

string

link.geo.SS

string

link.geo.XK

string

link.tagId

string | null

requireddeprecated

The unique ID of the tag assigned to the short link. This field is deprecated – use tags instead.

link.tags

object[] | null

required

The tags assigned to the short link.

Show child attributes

link.tags.id

string

required

The unique ID of the tag.

link.tags.name

string

required

The name of the tag.

link.tags.color

enum<string>

required

The color of the tag.

Available options:

red,

yellow,

green,

blue,

purple,

pink,

brown

link.webhookIds

string[]

required

The IDs of the webhooks that the short link is associated with.

link.comments

string | null

required

The comments for the short link.

link.shortLink

string

required

The full URL of the short link, including the https protocol (e.g. https://dub.sh/try).

link.qrCode

string

required

The full URL of the QR code for the short link (e.g. https://api.dub.co/qr?url=https://dub.sh/try).

link.utm_source

string | null

required

The UTM source of the short link.

link.utm_medium

string | null

required

The UTM medium of the short link.

link.utm_campaign

string | null

required

The UTM campaign of the short link.

link.utm_term

string | null

required

The UTM term of the short link.

link.utm_content

string | null

required

The UTM content of the short link.

link.userId

string | null

required

link.workspaceId

string

required

The workspace ID of the short link.

link.clicks

number

default: 0required

The number of clicks on the short link.

link.lastClicked

string

required

link.leads

number

default: 0required

[BETA]: The number of leads the short links has generated.

link.sales

number

default: 0required

[BETA]: The number of sales the short links has generated.

link.saleAmount

number

default: 0required

[BETA]: The total dollar amount of sales the short links has generated (in cents).

link.createdAt

string

required

link.updatedAt

string

required

link.projectId

string

requireddeprecated

The project ID of the short link. This field is deprecated – use workspaceId instead.

link.programId

string | null

required

The ID of the program the short link is associated with.

link.trackConversion

boolean

link.archived

boolean

link.proxy

boolean

link.rewrite

boolean

link.doIndex

boolean

link.publicStats

boolean

click_id

string

requireddeprecated

Deprecated. Use click.id instead.

link_id

string

requireddeprecated

Deprecated. Use link.id instead.

domain

string

requireddeprecated

Deprecated. Use link.domain instead.

key

string

requireddeprecated

Deprecated. Use link.key instead.

url

string

requireddeprecated

Deprecated. Use click.url instead.

continent

string

requireddeprecated

Deprecated. Use click.continent instead.

country

string

requireddeprecated

Deprecated. Use click.country instead.

city

string

requireddeprecated

Deprecated. Use click.city instead.

device

string

requireddeprecated

Deprecated. Use click.device instead.

browser

string

requireddeprecated

Deprecated. Use click.browser instead.

os

string

requireddeprecated

Deprecated. Use click.os instead.

qr

number

requireddeprecated

Deprecated. Use click.qr instead.

ip

string

requireddeprecated

Deprecated. Use click.ip instead.