Dub Events API
The Events API from Dub — 1 operation(s) for events.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dub Analytics Events API
description: Dub is the modern link attribution platform for short links, conversion tracking, and affiliate programs.
version: 0.0.1
contact:
name: Dub Support
email: support@dub.co
url: https://dub.co/support
license:
name: AGPL-3.0 license
url: https://github.com/dubinc/dub/blob/main/LICENSE.md
servers:
- url: https://api.dub.co
description: Production API
tags:
- name: Events
paths:
/events:
get:
operationId: listEvents
x-speakeasy-name-override: list
summary: List all events
description: Retrieve a paginated list of events for the authenticated workspace.
tags:
- Events
security:
- token: []
parameters:
- in: query
name: event
schema:
default: clicks
description: The type of event to retrieve analytics for. Defaults to 'clicks'.
type: string
enum:
- clicks
- leads
- sales
description: The type of event to retrieve analytics for. Defaults to 'clicks'.
- in: query
name: domain
schema:
description: 'The domain to filter analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `dub.co`, `dub.co,google.com`, `-spam.com`.'
example: dub.co
type: string
description: 'The domain to filter analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `dub.co`, `dub.co,google.com`, `-spam.com`.'
- in: query
name: key
schema:
description: 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.
type: string
description: 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.
- in: query
name: linkId
schema:
description: 'The unique ID of the link to retrieve analytics for.Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `link_123`, `link_123,link_456`, `-link_789`.'
type: string
description: 'The unique ID of the link to retrieve analytics for.Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `link_123`, `link_123,link_456`, `-link_789`.'
- in: query
name: externalId
schema:
description: The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.
type: string
description: The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.
- in: query
name: tenantId
schema:
description: '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 `-`). Examples: `tenant_123`, `tenant_123,tenant_456`, `-tenant_789`.'
type: string
description: '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 `-`). Examples: `tenant_123`, `tenant_123,tenant_456`, `-tenant_789`.'
- in: query
name: tagId
schema:
description: 'The tag ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `tag_123`, `tag_123,tag_456`, `-tag_789`.'
type: string
description: 'The tag ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `tag_123`, `tag_123,tag_456`, `-tag_789`.'
- in: query
name: folderId
schema:
description: 'The folder ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `folder_123`, `folder_123,folder_456`, `-folder_789`. If not provided, return analytics for all links.'
type: string
description: 'The folder ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `folder_123`, `folder_123,folder_456`, `-folder_789`. If not provided, return analytics for all links.'
- in: query
name: partnerTagId
schema:
description: 'The partner tag ID(s) to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `ptag_123`, `ptag_123,ptag_456`, `-ptag_789`.'
type: string
description: 'The partner tag ID(s) to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `ptag_123`, `ptag_123,ptag_456`, `-ptag_789`.'
- in: query
name: groupId
schema:
description: 'The group ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `grp_123`, `grp_123,grp_456`, `-grp_789`.'
type: string
description: 'The group ID to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `grp_123`, `grp_123,grp_456`, `-grp_789`.'
- in: query
name: partnerId
schema:
description: 'The ID of the partner to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `pn_123`, `pn_123,pn_456`, `-pn_789`.'
type: string
description: 'The ID of the partner to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `pn_123`, `pn_123,pn_456`, `-pn_789`.'
- in: query
name: customerId
schema:
description: The ID of the customer to retrieve analytics for.
type: string
description: The ID of the customer to retrieve analytics for.
- in: query
name: interval
schema:
description: The interval to retrieve analytics for. If undefined, defaults to 24h.
type: string
enum:
- 24h
- 7d
- 30d
- 90d
- 1y
- mtd
- qtd
- ytd
- all
description: The interval to retrieve analytics for. If undefined, defaults to 24h.
- in: query
name: start
schema:
description: The start date and time when to retrieve analytics from. If set, takes precedence over `interval`.
type: string
description: The start date and time when to retrieve analytics from. If set, takes precedence over `interval`.
- in: query
name: end
schema:
description: 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`.
type: string
description: 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`.
- in: query
name: timezone
schema:
description: The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.
example: America/New_York
default: UTC
type: string
description: The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.
- in: query
name: country
schema:
description: 'The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code (see https://d.to/geo). Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `US`, `US,BR,FR`, `-US`.'
type: string
description: 'The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code (see https://d.to/geo). Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `US`, `US,BR,FR`, `-US`.'
- in: query
name: city
schema:
description: 'The city to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `New York`, `New York,London`, `-New York`.'
type: string
description: 'The city to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `New York`, `New York,London`, `-New York`.'
- in: query
name: region
schema:
description: 'The ISO 3166-2 region code to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `NY`, `NY,CA`, `-NY`.'
type: string
description: 'The ISO 3166-2 region code to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `NY`, `NY,CA`, `-NY`.'
- in: query
name: continent
schema:
description: 'The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `NA`, `NA,EU`, `-AS`.'
type: string
description: 'The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `NA`, `NA,EU`, `-AS`.'
- in: query
name: device
schema:
description: 'The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Desktop`, `Mobile,Tablet`, `-Mobile`.'
type: string
description: 'The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Desktop`, `Mobile,Tablet`, `-Mobile`.'
- in: query
name: browser
schema:
description: 'The browser to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Chrome`, `Chrome,Firefox,Safari`, `-IE`.'
type: string
description: 'The browser to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Chrome`, `Chrome,Firefox,Safari`, `-IE`.'
- in: query
name: os
schema:
description: 'The OS to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Windows`, `Mac,Windows,Linux`, `-Windows`.'
type: string
description: 'The OS to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `Windows`, `Mac,Windows,Linux`, `-Windows`.'
- in: query
name: trigger
schema:
description: 'The trigger to retrieve analytics for. Valid values: qr, link, pageview. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `qr`, `qr,link`, `-qr`. If undefined, returns all trigger types.'
type: string
description: 'The trigger to retrieve analytics for. Valid values: qr, link, pageview. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `qr`, `qr,link`, `-qr`. If undefined, returns all trigger types.'
- in: query
name: referer
schema:
description: 'The referer hostname to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `google.com`, `google.com,twitter.com`, `-facebook.com`.'
type: string
description: 'The referer hostname to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `google.com`, `google.com,twitter.com`, `-facebook.com`.'
- in: query
name: refererUrl
schema:
description: 'The full referer URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `https://google.com`, `https://google.com,https://twitter.com`, `-https://spam.com`.'
type: string
description: 'The full referer URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `https://google.com`, `https://google.com,https://twitter.com`, `-https://spam.com`.'
- in: query
name: url
schema:
description: 'The destination URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `https://example.com`, `https://example.com,https://other.com`, `-https://spam.com`.'
type: string
description: 'The destination URL to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `https://example.com`, `https://example.com,https://other.com`, `-https://spam.com`.'
- in: query
name: utm_source
schema:
description: 'The UTM source to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `google`, `google,twitter`, `-spam`.'
type: string
description: 'The UTM source to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `google`, `google,twitter`, `-spam`.'
- in: query
name: utm_medium
schema:
description: 'The UTM medium to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `cpc`, `cpc,social`, `-email`.'
type: string
description: 'The UTM medium to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `cpc`, `cpc,social`, `-email`.'
- in: query
name: utm_campaign
schema:
description: 'The UTM campaign to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `summer_sale`, `summer_sale,winter_sale`, `-old_campaign`.'
type: string
description: 'The UTM campaign to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). Examples: `summer_sale`, `summer_sale,winter_sale`, `-old_campaign`.'
- in: query
name: utm_term
schema:
description: 'The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).'
type: string
description: 'The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).'
- in: query
name: utm_content
schema:
description: 'The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).'
type: string
description: 'The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).'
- in: query
name: root
schema:
description: Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.
type: boolean
description: Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.
- in: query
name: saleType
schema:
description: 'Filter sales by type: ''new'' for first-time purchases, ''recurring'' for repeat purchases. If undefined, returns both.'
type: string
enum:
- new
- recurring
description: 'Filter sales by type: ''new'' for first-time purchases, ''recurring'' for repeat purchases. If undefined, returns both.'
- in: query
name: query
schema:
description: 'Search the events by a custom metadata value. Only available for lead and sale events. Examples: `metadata[''key'']:''value''`'
type: string
maxLength: 10000
description: 'Search the events by a custom metadata value. Only available for lead and sale events. Examples: `metadata[''key'']:''value''`'
- in: query
name: programId
schema:
description: 'Deprecated: This is automatically inferred from your workspace''s defaultProgramId. The ID of the program to retrieve analytics for.'
deprecated: true
type: string
description: 'Deprecated: This is automatically inferred from your workspace''s defaultProgramId. The ID of the program to retrieve analytics for.'
- in: query
name: tagIds
schema:
description: 'Deprecated: Use `tagId` instead. The tag IDs to retrieve analytics for.'
deprecated: true
type: string
description: 'Deprecated: Use `tagId` instead. The tag IDs to retrieve analytics for.'
- in: query
name: qr
schema:
description: '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.'
deprecated: true
type: boolean
description: '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.'
- in: query
name: page
schema:
default: 1
type: number
- in: query
name: limit
schema:
default: 100
type: number
maximum: 1000
- in: query
name: sortOrder
schema:
description: The sort order. The default is `desc`.
default: desc
type: string
enum:
- asc
- desc
description: The sort order. The default is `desc`.
- in: query
name: sortBy
schema:
default: timestamp
description: The field to sort the events by. The default is `timestamp`.
type: string
enum:
- timestamp
description: The field to sort the events by. The default is `timestamp`.
- in: query
name: order
schema:
description: DEPRECATED. Use `sortOrder` instead.
deprecated: true
default: desc
type: string
enum:
- asc
- desc
description: DEPRECATED. Use `sortOrder` instead.
responses:
'200':
description: A list of events
content:
application/json:
schema:
type: array
items:
oneOf:
- type: object
properties:
event:
type: string
enum:
- click
timestamp:
type: string
click:
type: object
properties:
id:
type: string
timestamp:
type: string
url:
type: string
country:
type: string
city:
type: string
region:
type: string
continent:
type: string
device:
type: string
browser:
type: string
os:
type: string
trigger:
nullable: true
type: string
referer:
type: string
refererUrl:
type: string
qr:
type: boolean
ip:
type: string
required:
- id
- timestamp
- url
- country
- city
- region
- continent
- device
- browser
- os
- referer
- refererUrl
- qr
- ip
additionalProperties: false
link:
type: object
properties:
id:
type: string
description: The unique ID of the short link.
domain:
type: string
description: 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).
key:
type: string
description: The short link slug. If not provided, a random 7-character slug will be generated.
url:
type: string
trackConversion:
type: boolean
externalId:
nullable: true
description: The ID of the link in your database. 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). This key is unique across your workspace.
type: string
tenantId:
nullable: true
description: The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.
type: string
programId:
nullable: true
description: The ID of the program the short link is associated with.
type: string
partnerId:
nullable: true
description: The ID of the partner the short link is associated with.
type: string
archived:
type: boolean
expiresAt:
type: string
expiredUrl:
nullable: true
type: string
disabledAt:
type: string
password:
nullable: true
description: The password required to access the destination URL of the short link.
type: string
proxy:
type: boolean
title:
nullable: true
description: The title of the short link. Will be used for Custom Link Previews if `proxy` is true.
type: string
description:
nullable: true
description: The description of the short link. Will be used for Custom Link Previews if `proxy` is true.
type: string
image:
nullable: true
description: The image of the short link. Will be used for Custom Link Previews if `proxy` is true.
type: string
video:
nullable: true
description: 'The custom link preview video (og:video). Will be used for Custom Link Previews if `proxy` is true. Learn more: https://d.to/og'
type: string
rewrite:
type: boolean
doIndex:
type: boolean
ios:
nullable: true
description: The iOS destination URL for the short link for iOS device targeting.
type: string
android:
nullable: true
description: The Android destination URL for the short link for Android device targeting.
type: string
geo:
nullable: true
description: 'Geo targeting information for the short link in JSON format `{[COUNTRY]: https://example.com }`. See https://d.to/geo for more information.'
type: object
additionalProperties:
type: string
format: uri
publicStats:
type: boolean
tags:
nullable: true
description: The tags assigned to the short link.
type: array
items:
$ref: '#/components/schemas/LinkTagSchemaOutput'
folderId:
nullable: true
description: The unique ID of the folder assigned to the short link.
type: string
webhookIds:
type: array
items:
type: string
description: The IDs of the webhooks that the short link is associated with.
comments:
nullable: true
description: The comments for the short link.
type: string
shortLink:
type: string
format: uri
description: The full URL of the short link, including the https protocol (e.g. `https://dub.sh/try`).
qrCode:
type: string
format: uri
description: The full URL of the QR code for the short link (e.g. `https://api.dub.co/qr?url=https://dub.sh/try`).
utm_source:
nullable: true
description: The UTM source of the short link.
type: string
utm_medium:
nullable: true
description: The UTM medium of the short link.
type: string
utm_campaign:
nullable: true
description: The UTM campaign of the short link.
type: string
utm_term:
nullable: true
description: The UTM term of the short link.
type: string
utm_content:
nullable: true
description: The UTM content of the short link.
type: string
testVariants:
nullable: true
minItems: 2
maxItems: 4
type: array
items:
type: object
properties:
url:
type: string
percentage:
type: number
minimum: 10
maximum: 90
required:
- url
- percentage
additionalProperties: false
description: An array of A/B test URLs and the percentage of traffic to send to each URL.
example:
- url: https://example.com/variant-1
percentage: 50
- url: https://example.com/variant-2
percentage: 50
testStartedAt:
type: string
testCompletedAt:
type: string
userId:
nullable: true
type: string
workspaceId:
type: string
description: The workspace ID of the short link.
clicks:
default: 0
description: The number of clicks on the short link.
type: number
leads:
default: 0
description: The number of leads the short link has generated.
type: number
conversions:
default: 0
description: The number of leads that converted to paying customers.
type: number
sales:
default: 0
description: The total number of sales (includes recurring sales) generated by the short link.
type: number
saleAmount:
description: The total dollar value of sales (in cents) generated by the short link.
default: 0
type: number
la
# --- truncated at 32 KB (93 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-events-api-openapi.yml