GET
/
events
from dub import Dub


with Dub(
    token="DUB_API_KEY",
) as d_client:

    res = d_client.events.list(request={
        "city": "New York",
        "device": "Desktop",
        "browser": "Chrome",
        "os": "Windows",
        "referer": "google.com",
        "referer_url": "https://dub.co/blog",
    })

    assert res is not None

    # Handle response
    print(res)
[
  {
    "event": "click",
    "timestamp": "<string>",
    "click": {
      "id": "<string>",
      "timestamp": "<string>",
      "url": "<string>",
      "country": "<string>",
      "city": "<string>",
      "region": "<string>",
      "continent": "<string>",
      "device": "<string>",
      "browser": "<string>",
      "os": "<string>",
      "referer": "<string>",
      "refererUrl": "<string>",
      "qr": true,
      "ip": "<string>"
    },
    "link": {
      "id": "<string>",
      "domain": "<string>",
      "key": "<string>",
      "url": "<string>",
      "trackConversion": true,
      "externalId": "<string>",
      "tenantId": "<string>",
      "programId": "<string>",
      "partnerId": "<string>",
      "archived": true,
      "expiresAt": "<string>",
      "expiredUrl": "<string>",
      "password": "<string>",
      "proxy": true,
      "title": "<string>",
      "description": "<string>",
      "image": "<string>",
      "video": "<string>",
      "rewrite": true,
      "doIndex": true,
      "ios": "<string>",
      "android": "<string>",
      "geo": {
        "AF": "<string>",
        "AL": "<string>",
        "DZ": "<string>",
        "AS": "<string>",
        "AD": "<string>",
        "AO": "<string>",
        "AI": "<string>",
        "AQ": "<string>",
        "AG": "<string>",
        "AR": "<string>",
        "AM": "<string>",
        "AW": "<string>",
        "AU": "<string>",
        "AT": "<string>",
        "AZ": "<string>",
        "BS": "<string>",
        "BH": "<string>",
        "BD": "<string>",
        "BB": "<string>",
        "BY": "<string>",
        "BE": "<string>",
        "BZ": "<string>",
        "BJ": "<string>",
        "BM": "<string>",
        "BT": "<string>",
        "BO": "<string>",
        "BA": "<string>",
        "BW": "<string>",
        "BV": "<string>",
        "BR": "<string>",
        "IO": "<string>",
        "BN": "<string>",
        "BG": "<string>",
        "BF": "<string>",
        "BI": "<string>",
        "KH": "<string>",
        "CM": "<string>",
        "CA": "<string>",
        "CV": "<string>",
        "KY": "<string>",
        "CF": "<string>",
        "TD": "<string>",
        "CL": "<string>",
        "CN": "<string>",
        "CX": "<string>",
        "CC": "<string>",
        "CO": "<string>",
        "KM": "<string>",
        "CG": "<string>",
        "CD": "<string>",
        "CK": "<string>",
        "CR": "<string>",
        "CI": "<string>",
        "HR": "<string>",
        "CU": "<string>",
        "CY": "<string>",
        "CZ": "<string>",
        "DK": "<string>",
        "DJ": "<string>",
        "DM": "<string>",
        "DO": "<string>",
        "EC": "<string>",
        "EG": "<string>",
        "SV": "<string>",
        "GQ": "<string>",
        "ER": "<string>",
        "EE": "<string>",
        "ET": "<string>",
        "FK": "<string>",
        "FO": "<string>",
        "FJ": "<string>",
        "FI": "<string>",
        "FR": "<string>",
        "GF": "<string>",
        "PF": "<string>",
        "TF": "<string>",
        "GA": "<string>",
        "GM": "<string>",
        "GE": "<string>",
        "DE": "<string>",
        "GH": "<string>",
        "GI": "<string>",
        "GR": "<string>",
        "GL": "<string>",
        "GD": "<string>",
        "GP": "<string>",
        "GU": "<string>",
        "GT": "<string>",
        "GN": "<string>",
        "GW": "<string>",
        "GY": "<string>",
        "HT": "<string>",
        "HM": "<string>",
        "VA": "<string>",
        "HN": "<string>",
        "HK": "<string>",
        "HU": "<string>",
        "IS": "<string>",
        "IN": "<string>",
        "ID": "<string>",
        "IR": "<string>",
        "IQ": "<string>",
        "IE": "<string>",
        "IL": "<string>",
        "IT": "<string>",
        "JM": "<string>",
        "JP": "<string>",
        "JO": "<string>",
        "KZ": "<string>",
        "KE": "<string>",
        "KI": "<string>",
        "KP": "<string>",
        "KR": "<string>",
        "KW": "<string>",
        "KG": "<string>",
        "LA": "<string>",
        "LV": "<string>",
        "LB": "<string>",
        "LS": "<string>",
        "LR": "<string>",
        "LY": "<string>",
        "LI": "<string>",
        "LT": "<string>",
        "LU": "<string>",
        "MO": "<string>",
        "MG": "<string>",
        "MW": "<string>",
        "MY": "<string>",
        "MV": "<string>",
        "ML": "<string>",
        "MT": "<string>",
        "MH": "<string>",
        "MQ": "<string>",
        "MR": "<string>",
        "MU": "<string>",
        "YT": "<string>",
        "MX": "<string>",
        "FM": "<string>",
        "MD": "<string>",
        "MC": "<string>",
        "MN": "<string>",
        "MS": "<string>",
        "MA": "<string>",
        "MZ": "<string>",
        "MM": "<string>",
        "NA": "<string>",
        "NR": "<string>",
        "NP": "<string>",
        "NL": "<string>",
        "NC": "<string>",
        "NZ": "<string>",
        "NI": "<string>",
        "NE": "<string>",
        "NG": "<string>",
        "NU": "<string>",
        "NF": "<string>",
        "MK": "<string>",
        "MP": "<string>",
        "NO": "<string>",
        "OM": "<string>",
        "PK": "<string>",
        "PW": "<string>",
        "PS": "<string>",
        "PA": "<string>",
        "PG": "<string>",
        "PY": "<string>",
        "PE": "<string>",
        "PH": "<string>",
        "PN": "<string>",
        "PL": "<string>",
        "PT": "<string>",
        "PR": "<string>",
        "QA": "<string>",
        "RE": "<string>",
        "RO": "<string>",
        "RU": "<string>",
        "RW": "<string>",
        "SH": "<string>",
        "KN": "<string>",
        "LC": "<string>",
        "PM": "<string>",
        "VC": "<string>",
        "WS": "<string>",
        "SM": "<string>",
        "ST": "<string>",
        "SA": "<string>",
        "SN": "<string>",
        "SC": "<string>",
        "SL": "<string>",
        "SG": "<string>",
        "SK": "<string>",
        "SI": "<string>",
        "SB": "<string>",
        "SO": "<string>",
        "ZA": "<string>",
        "GS": "<string>",
        "ES": "<string>",
        "LK": "<string>",
        "SD": "<string>",
        "SR": "<string>",
        "SJ": "<string>",
        "SZ": "<string>",
        "SE": "<string>",
        "CH": "<string>",
        "SY": "<string>",
        "TW": "<string>",
        "TJ": "<string>",
        "TZ": "<string>",
        "TH": "<string>",
        "TL": "<string>",
        "TG": "<string>",
        "TK": "<string>",
        "TO": "<string>",
        "TT": "<string>",
        "TN": "<string>",
        "TR": "<string>",
        "TM": "<string>",
        "TC": "<string>",
        "TV": "<string>",
        "UG": "<string>",
        "UA": "<string>",
        "AE": "<string>",
        "GB": "<string>",
        "US": "<string>",
        "UM": "<string>",
        "UY": "<string>",
        "UZ": "<string>",
        "VU": "<string>",
        "VE": "<string>",
        "VN": "<string>",
        "VG": "<string>",
        "VI": "<string>",
        "WF": "<string>",
        "EH": "<string>",
        "YE": "<string>",
        "ZM": "<string>",
        "ZW": "<string>",
        "AX": "<string>",
        "BQ": "<string>",
        "CW": "<string>",
        "GG": "<string>",
        "IM": "<string>",
        "JE": "<string>",
        "ME": "<string>",
        "BL": "<string>",
        "MF": "<string>",
        "RS": "<string>",
        "SX": "<string>",
        "SS": "<string>",
        "XK": "<string>"
      },
      "publicStats": true,
      "tagId": "<string>",
      "tags": [
        {
          "id": "<string>",
          "name": "<string>",
          "color": "red"
        }
      ],
      "folderId": "<string>",
      "webhookIds": [
        "<string>"
      ],
      "comments": "<string>",
      "shortLink": "<string>",
      "qrCode": "<string>",
      "utm_source": "<string>",
      "utm_medium": "<string>",
      "utm_campaign": "<string>",
      "utm_term": "<string>",
      "utm_content": "<string>",
      "userId": "<string>",
      "workspaceId": "<string>",
      "clicks": 0,
      "lastClicked": "<string>",
      "leads": 0,
      "sales": 0,
      "saleAmount": 0,
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "projectId": "<string>"
    },
    "click_id": "<string>",
    "link_id": "<string>",
    "domain": "<string>",
    "key": "<string>",
    "url": "<string>",
    "continent": "<string>",
    "country": "<string>",
    "city": "<string>",
    "device": "<string>",
    "browser": "<string>",
    "os": "<string>",
    "qr": 123,
    "ip": "<string>"
  }
]

Events endpoints require a Business plan subscription or higher.

Authorizations

​
Authorization
string
header
required

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.

​
tenantId
string

The ID of the tenant that created the link inside your system.

​
programId
string

The ID of the program to retrieve analytics for.

​
partnerId
string

The ID of the partner to retrieve analytics for.

​
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,
1y,
mtd,
qtd,
ytd,
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.

Example:

"America/New_York"

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

Example:

"New York"

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

Example:

"Desktop"

​
browser
string

The browser to retrieve analytics for.

Example:

"Chrome"

​
os
string

The OS to retrieve analytics for.

Example:

"Windows"

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

Example:

"google.com"

​
refererUrl
string

The full referer URL to retrieve analytics for.

Example:

"https://dub.co/blog"

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

​
folderId
string

The folder ID to retrieve analytics for. If not provided, return analytics for unsorted links.

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

​
utm_source
string | null

The UTM source of the short link.

Maximum length: 190
​
utm_medium
string | null

The UTM medium of the short link.

Maximum length: 190
​
utm_campaign
string | null

The UTM campaign of the short link.

Maximum length: 190
​
utm_term
string | null

The UTM term of the short link.

Maximum length: 190
​
utm_content
string | null

The UTM content of the short link.

Maximum length: 190
​
page
number
default:1
​
limit
number
default:100
​
sortOrder
enum<string>
default:desc

The sort order. The default is desc.

Available options:
asc,
desc
​
sortBy
enum<string>
default:timestamp

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

Available options:
timestamp
​
order
enum<string>
default:desc
deprecated

DEPRECATED. Use sortOrder instead.

Available options:
asc,
desc

Response

200
application/json
A list of events
​
event
enum<string>
required
Available options:
click
​
click
object
required
​
link
object
required
​
click_id
string
required
deprecated

Deprecated. Use click.id instead.

​
link_id
string
required
deprecated

Deprecated. Use link.id instead.

​
domain
string
required
deprecated

Deprecated. Use link.domain instead.

​
key
string
required
deprecated

Deprecated. Use link.key instead.

​
url
string
required
deprecated

Deprecated. Use click.url instead.

​
continent
string
required
deprecated

Deprecated. Use click.continent instead.

​
country
string
required
deprecated

Deprecated. Use click.country instead.

​
city
string
required
deprecated

Deprecated. Use click.city instead.

​
device
string
required
deprecated

Deprecated. Use click.device instead.

​
browser
string
required
deprecated

Deprecated. Use click.browser instead.

​
os
string
required
deprecated

Deprecated. Use click.os instead.

​
qr
number
required
deprecated

Deprecated. Use click.qr instead.

​
ip
string
required
deprecated

Deprecated. Use click.ip instead.

​
timestamp
string

Was this page helpful?

Suggest editsRaise issue