Dub Analytics API
The Analytics API from Dub — 1 operation(s) for analytics.
OpenAPI Specification
openapi: 3.0.3
info:
title: Dub Analytics 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: Analytics
paths:
/analytics:
get:
operationId: retrieveAnalytics
x-speakeasy-name-override: retrieve
summary: Retrieve analytics for a link, a domain, or the authenticated workspace.
description: Retrieve analytics for a link, a domain, or the authenticated workspace. The response type depends on the `event` and `type` query parameters.
tags:
- Analytics
security:
- token: []
parameters:
- in: query
name: event
schema:
default: clicks
description: The type of event to retrieve analytics for. Defaults to `clicks`.
example: leads
type: string
enum:
- clicks
- leads
- sales
- composite
description: The type of event to retrieve analytics for. Defaults to `clicks`.
- in: query
name: groupBy
schema:
default: count
description: The parameter to group the analytics data points by. Defaults to `count` if undefined.
type: string
enum:
- count
- timeseries
- continents
- regions
- countries
- cities
- devices
- browsers
- os
- trigger
- triggers
- referers
- referer_urls
- top_folders
- top_link_tags
- top_domains
- top_links
- top_urls
- top_base_urls
- top_partners
- top_groups
- top_partner_tags
- utm_sources
- utm_mediums
- utm_campaigns
- utm_terms
- utm_contents
description: The parameter to group the analytics data points by. Defaults to `count` if undefined.
- 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.'
responses:
'200':
description: Analytics data
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AnalyticsCount'
- type: array
items:
$ref: '#/components/schemas/AnalyticsTimeseries'
- type: array
items:
$ref: '#/components/schemas/AnalyticsContinents'
- type: array
items:
$ref: '#/components/schemas/AnalyticsCountries'
- type: array
items:
$ref: '#/components/schemas/AnalyticsRegions'
- type: array
items:
$ref: '#/components/schemas/AnalyticsCities'
- type: array
items:
$ref: '#/components/schemas/AnalyticsDevices'
- type: array
items:
$ref: '#/components/schemas/AnalyticsBrowsers'
- type: array
items:
$ref: '#/components/schemas/AnalyticsOS'
- type: array
items:
$ref: '#/components/schemas/AnalyticsTriggers'
- type: array
items:
$ref: '#/components/schemas/AnalyticsReferers'
- type: array
items:
$ref: '#/components/schemas/AnalyticsRefererUrls'
- type: array
items:
$ref: '#/components/schemas/AnalyticsTopLinks'
- type: array
items:
$ref: '#/components/schemas/AnalyticsTopUrls'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
$ref: '#/components/responses/409'
'410':
$ref: '#/components/responses/410'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
components:
schemas:
AnalyticsOS:
type: object
properties:
os:
type: string
description: The name of the OS
clicks:
default: 0
type: number
description: The number of clicks from this OS
leads:
default: 0
type: number
description: The number of leads from this OS
sales:
default: 0
type: number
description: The number of sales from this OS
saleAmount:
description: The total amount of sales from this OS, in cents
default: 0
type: number
required:
- os
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsTopLinks:
type: object
properties:
link:
type: string
description: The unique ID of the short link
deprecated: true
id:
type: string
description: The unique ID of the short link
domain:
type: string
description: The domain of the short link
key:
type: string
description: The key of the short link
shortLink:
type: string
description: The short link URL
url:
type: string
description: The destination URL of the short link
title:
description: The custom link preview title (og:title)
nullable: true
type: string
comments:
description: The comments of the short link
nullable: true
type: string
folderId:
description: The ID of the folder that the link belongs to (if applicable)
nullable: true
type: string
partnerId:
description: The ID of the partner that the link belongs to (if applicable)
nullable: true
type: string
createdAt:
type: string
description: The creation timestamp of the short link
clicks:
default: 0
type: number
description: The number of clicks from this link
leads:
default: 0
type: number
description: The number of leads from this link
sales:
default: 0
type: number
description: The number of sales from this link
saleAmount:
description: The total amount of sales from this link, in cents
default: 0
type: number
required:
- link
- id
- domain
- key
- shortLink
- url
- createdAt
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsCount:
type: object
properties:
clicks:
default: 0
type: number
description: The total number of clicks
leads:
default: 0
type: number
description: The total number of leads
sales:
default: 0
type: number
description: The total number of sales
saleAmount:
description: The total amount of sales, in cents
default: 0
type: number
required:
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsTimeseries:
type: object
properties:
start:
type: string
description: The starting timestamp of the interval
clicks:
default: 0
type: number
description: The number of clicks in the interval
leads:
default: 0
type: number
description: The number of leads in the interval
sales:
default: 0
type: number
description: The number of sales in the interval
saleAmount:
description: The total amount of sales in the interval, in cents
default: 0
type: number
required:
- start
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsTriggers:
type: object
properties:
trigger:
type: string
enum:
- qr
- link
- pageview
- deeplink
description: 'The type of trigger method: link click or QR scan'
clicks:
default: 0
type: number
description: The number of clicks from this trigger method
leads:
default: 0
type: number
description: The number of leads from this trigger method
sales:
default: 0
type: number
description: The number of sales from this trigger method
saleAmount:
description: The total amount of sales from this trigger method, in cents
default: 0
type: number
required:
- trigger
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsRefererUrls:
type: object
properties:
refererUrl:
type: string
description: The full URL of the referer. If unknown, this will be `(direct)`
clicks:
default: 0
type: number
description: The number of clicks from this referer to this URL
leads:
default: 0
type: number
description: The number of leads from this referer to this URL
sales:
default: 0
type: number
description: The number of sales from this referer to this URL
saleAmount:
description: The total amount of sales from this referer to this URL, in cents
default: 0
type: number
required:
- refererUrl
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsTopUrls:
type: object
properties:
url:
type: string
description: The full destination URL (including query parameters)
clicks:
default: 0
type: number
description: The number of clicks from this URL
leads:
default: 0
type: number
description: The number of leads from this URL
sales:
default: 0
type: number
description: The number of sales from this URL
saleAmount:
description: The total amount of sales from this URL, in cents
default: 0
type: number
required:
- url
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsCountries:
type: object
properties:
country:
type: string
description: 'The 2-letter ISO 3166-1 country code of the country. Learn more: https://d.to/geo'
region:
default: '*'
type: string
enum:
- '*'
city:
default: '*'
type: string
enum:
- '*'
clicks:
default: 0
type: number
description: The number of clicks from this country
leads:
default: 0
type: number
description: The number of leads from this country
sales:
default: 0
type: number
description: The number of sales from this country
saleAmount:
description: The total amount of sales from this country, in cents
default: 0
type: number
required:
- country
- region
- city
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsReferers:
type: object
properties:
referer:
type: string
description: The name of the referer. If unknown, this will be `(direct)`
clicks:
default: 0
type: number
description: The number of clicks from this referer
leads:
default: 0
type: number
description: The number of leads from this referer
sales:
default: 0
type: number
description: The number of sales from this referer
saleAmount:
description: The total amount of sales from this referer, in cents
default: 0
type: number
required:
- referer
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsContinents:
type: object
properties:
continent:
type: string
enum:
- AF
- AN
- AS
- EU
- NA
- OC
- SA
description: The 2-letter ISO 3166-1 code representing the continent associated with the location of the user.
clicks:
default: 0
type: number
description: The number of clicks from this continent
leads:
default: 0
type: number
description: The number of leads from this continent
sales:
default: 0
type: number
description: The number of sales from this continent
saleAmount:
description: The total amount of sales from this continent, in cents
default: 0
type: number
required:
- continent
- clicks
- leads
- sales
- saleAmount
additionalProperties: false
AnalyticsCities:
type: object
properties:
country:
type: string
description: 'The 2-letter ISO 3166-1 country code of the country where this city is located. Learn more: https://d.to/geo'
region:
type:
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dub/refs/heads/main/openapi/dub-analytics-api-openapi.yml