List all events

Retrieve a paginated list of events for the authenticated workspace.

1 min read

get/events

Request example

from dub import Dub


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

    res = d_client.events.list(request={
        "domain": "dub.co",
        "timezone": "America/New_York",
        "city": "New York",
        "device": "Desktop",
        "browser": "Chrome",
        "os": "Windows",
        "referer": "google.com",
        "referer_url": "https://dub.co/blog",
        "query": "metadata['key']:'value'",
    })

    # Handle response
    print(res)

Response

[
  {
    "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>",
      "ua": "<string>",
      "trigger": "<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>",
      "disabledAt": "<string>",
      "password": "<string>",
      "proxy": true,
      "title": "<string>",
      "description": "<string>",
      "image": "<string>",
      "video": "<string>",
      "rewrite": true,
      "doIndex": true,
      "ios": "<string>",
      "android": "<string>",
      "geo": {},
      "publicStats": true,
      "tags": [
        {
          "id": "<string>",
          "name": "<string>",
          "color": "red"
        }
      ],
      "folderId": "<string>",
      "comments": "<string>",
      "shortLink": "<string>",
      "qrCode": "<string>",
      "utm_source": "<string>",
      "utm_medium": "<string>",
      "utm_campaign": "<string>",
      "utm_term": "<string>",
      "utm_content": "<string>",
      "testVariants": [
        {
          "url": "https://example.com/variant-1",
          "percentage": 50
        },
        {
          "url": "https://example.com/variant-2",
          "percentage": 50
        }
      ],
      "testStartedAt": "<string>",
      "testCompletedAt": "<string>",
      "userId": "<string>",
      "workspaceId": "<string>",
      "clicks": 0,
      "leads": 0,
      "conversions": 0,
      "sales": 0,
      "saleAmount": 0,
      "lastClicked": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>",
      "tagId": "<string>",
      "projectId": "<string>",
      "webhookIds": [
        "<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": 1,
    "ip": "<string>"
  }
]

get/events

Note

Events endpoints require a Business plan subscription or higher.

Authorization

Authorizationstringheaderrequired#

Default authentication mechanism

Query parameters

eventenum<string>#

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

Default: "clicks"

Options:clicksleadssales

domainstring#

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.

keystring#

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.

linkIdstring#

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.

externalIdstring#

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

tenantIdstring#

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.

tagIdstring#

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.

folderIdstring#

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.

partnerTagIdstring#

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.

groupIdstring#

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.

partnerIdstring#

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.

customerIdstring#

The ID of the customer to retrieve analytics for.

intervalenum<string>#

The interval to retrieve analytics for. If undefined, defaults to 24h.

Options:24h7d30d90d1ymtdqtdytdall

startstring#

The start date and time when to retrieve analytics from. If set, takes precedence over interval.

endstring#

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.

timezonestring#

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

Default: "UTC"

countrystring#

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.

citystring#

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.

regionstring#

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.

continentstring#

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.

devicestring#

The device to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Desktop, Mobile,Tablet, -Mobile.

browserstring#

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.

osstring#

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.

triggerstring#

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.

eventNamestring#

The conversion event name to retrieve analytics for. Only available for lead and sale events. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: Sign up, Sign up,Purchase, -Sign up.

refererstring#

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.

refererUrlstring#

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.

urlstring#

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.

utm_sourcestring#

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.

utm_mediumstring#

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.

utm_campaignstring#

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.

utm_termstring#

The UTM term to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

utm_contentstring#

The UTM content to retrieve analytics for. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -).

rootboolean#

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

saleTypeenum<string>#

Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both.

Options:newrecurring

querystring#

Search the events by a custom metadata value. Only available for lead and sale events. Examples: metadata['key']:'value'

Length: max 10000

programIdstringdeprecated#

Deprecated: This is automatically inferred from your workspace's defaultProgramId. The ID of the program to retrieve analytics for.

tagIdsstringdeprecated#

Deprecated: Use tagId instead. The tag IDs to retrieve analytics for.

qrbooleandeprecated#

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.

pageinteger#

The page number for pagination. The first page is 1.

Default: 1

Range: true < x <= 9007199254740991

limitinteger#

The number of items per page.

Default: 100

Range: true < x <= 1000

sortOrderenum<string>#

The sort order. The default is desc.

Default: "desc"

Options:ascdesc

sortByenum<string>#

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

Default: "timestamp"

Options:timestamp

orderenum<string>deprecated#

DEPRECATED. Use sortOrder instead.

Default: "desc"

Options:ascdesc

Responses

application/json

A list of events

One of

eventenum<string>required#

Options:click

timestampstringrequired#

clickobjectrequired#

Show child attributes

idstringrequired#

timestampstringrequired#

urlstringrequired#

countrystringrequired#

citystringrequired#

regionstringrequired#

continentstringrequired#

devicestringrequired#

browserstringrequired#

osstringrequired#

uastring#

triggerstring#

refererstringrequired#

refererUrlstringrequired#

qrbooleanrequired#

ipstringrequired#

linkobjectrequired#

Show child attributes

idstringrequired#

The unique ID of the short link.

domainstringrequired#

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

keystringrequired#

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

urlstringrequired#

trackConversionbooleanrequired#

externalIdstringrequired#

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.

tenantIdstringrequired#

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.

programIdstringrequired#

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

partnerIdstringrequired#

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

archivedbooleanrequired#

expiresAtstringrequired#

expiredUrlstringrequired#

disabledAtstringrequired#

passwordstringrequired#

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

proxybooleanrequired#

titlestringrequired#

The title of the short link. Will be used for Custom Link Previews if proxy is true.

descriptionstringrequired#

The description of the short link. Will be used for Custom Link Previews if proxy is true.

imagestringrequired#

The image of the short link. Will be used for Custom Link Previews if proxy is true.

videostringrequired#

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

rewritebooleanrequired#

doIndexbooleanrequired#

iosstringrequired#

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

androidstringrequired#

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

geoobjectrequired#

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

Show child attributes

{key}string#

publicStatsbooleanrequired#

tagsobject[]required#

The tags assigned to the short link.

Show child attributes

idstringrequired#

The unique ID of the tag.

namestringrequired#

The name of the tag.

colorenum<string>required#

The color of the tag.

Options:redyellowgreenbluepurplebrowngraypink

folderIdstringrequired#

The unique ID of the folder assigned to the short link.

commentsstringrequired#

The comments for the short link.

shortLinkstringrequired#

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

qrCodestringrequired#

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

utm_sourcestringrequired#

The UTM source of the short link.

utm_mediumstringrequired#

The UTM medium of the short link.

utm_campaignstringrequired#

The UTM campaign of the short link.

utm_termstringrequired#

The UTM term of the short link.

utm_contentstringrequired#

The UTM content of the short link.

testVariantsobject[]#

An array of A/B test URLs and the percentage of traffic to send to each URL.

Items: 2–4

Show child attributes

urlstringrequired#

percentagenumberrequired#

Range: 10–90

testStartedAtstringrequired#

testCompletedAtstringrequired#

userIdstringrequired#

workspaceIdstringrequired#

The workspace ID of the short link.

clicksnumberrequired#

The number of clicks on the short link.

Default: 0

leadsnumberrequired#

The number of leads the short link has generated.

Default: 0

conversionsnumberrequired#

The number of leads that converted to paying customers.

Default: 0

salesnumberrequired#

The total number of sales (includes recurring sales) generated by the short link.

Default: 0

saleAmountnumberrequired#

The total dollar value of sales (in cents) generated by the short link.

Default: 0

lastClickedstringrequired#

createdAtstringrequired#

updatedAtstringrequired#

tagIdstringrequireddeprecated#

Deprecated: Use tags instead. The unique ID of the tag assigned to the short link.

projectIdstringrequireddeprecated#

Deprecated: Use workspaceId instead. The project ID of the short link.

webhookIdsstring[]requireddeprecated#

Deprecated: You can now enable link.clicked webhooks for all links in a workspace or folder without passing this field manually. An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

click_idstringrequireddeprecated#

Deprecated: Use click.id instead.

link_idstringrequireddeprecated#

Deprecated: Use link.id instead.

domainstringrequireddeprecated#

Deprecated: Use link.domain instead.

keystringrequireddeprecated#

Deprecated: Use link.key instead.

urlstringrequireddeprecated#

Deprecated: Use click.url instead.

continentstringrequireddeprecated#

Deprecated: Use click.continent instead.

countrystringrequireddeprecated#

Deprecated: Use click.country instead.

citystringrequireddeprecated#

Deprecated: Use click.city instead.

devicestringrequireddeprecated#

Deprecated: Use click.device instead.

browserstringrequireddeprecated#

Deprecated: Use click.browser instead.

osstringrequireddeprecated#

Deprecated: Use click.os instead.

qrnumberrequireddeprecated#

Deprecated: Use click.qr instead.

ipstringrequireddeprecated#

Deprecated: Use click.ip instead.

eventenum<string>required#

Options:lead

timestampstringrequired#

eventIdstringrequired#

eventNamestringrequired#

metadataany#

clickobjectrequired#

Show child attributes

idstringrequired#

timestampstringrequired#

urlstringrequired#

countrystringrequired#

citystringrequired#

regionstringrequired#

continentstringrequired#

devicestringrequired#

browserstringrequired#

osstringrequired#

uastring#

triggerstring#

refererstringrequired#

refererUrlstringrequired#

qrbooleanrequired#

ipstringrequired#

linkobjectrequired#

Show child attributes

idstringrequired#

The unique ID of the short link.

domainstringrequired#

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

keystringrequired#

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

urlstringrequired#

trackConversionbooleanrequired#

externalIdstringrequired#

tenantIdstringrequired#

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.

programIdstringrequired#

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

partnerIdstringrequired#

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

archivedbooleanrequired#

expiresAtstringrequired#

expiredUrlstringrequired#

disabledAtstringrequired#

passwordstringrequired#

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

proxybooleanrequired#

titlestringrequired#

The title of the short link. Will be used for Custom Link Previews if proxy is true.

descriptionstringrequired#

The description of the short link. Will be used for Custom Link Previews if proxy is true.

imagestringrequired#

The image of the short link. Will be used for Custom Link Previews if proxy is true.

videostringrequired#

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

rewritebooleanrequired#

doIndexbooleanrequired#

iosstringrequired#

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

androidstringrequired#

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

geoobjectrequired#

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

Show child attributes

{key}string#

publicStatsbooleanrequired#

tagsobject[]required#

The tags assigned to the short link.

Show child attributes

idstringrequired#

The unique ID of the tag.

namestringrequired#

The name of the tag.

colorenum<string>required#

The color of the tag.

Options:redyellowgreenbluepurplebrowngraypink

folderIdstringrequired#

The unique ID of the folder assigned to the short link.

commentsstringrequired#

The comments for the short link.

shortLinkstringrequired#

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

qrCodestringrequired#

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

utm_sourcestringrequired#

The UTM source of the short link.

utm_mediumstringrequired#

The UTM medium of the short link.

utm_campaignstringrequired#

The UTM campaign of the short link.

utm_termstringrequired#

The UTM term of the short link.

utm_contentstringrequired#

The UTM content of the short link.

testVariantsobject[]#

An array of A/B test URLs and the percentage of traffic to send to each URL.

Items: 2–4

Show child attributes

urlstringrequired#

percentagenumberrequired#

Range: 10–90

testStartedAtstringrequired#

testCompletedAtstringrequired#

userIdstringrequired#

workspaceIdstringrequired#

The workspace ID of the short link.

clicksnumberrequired#

The number of clicks on the short link.

Default: 0

leadsnumberrequired#

The number of leads the short link has generated.

Default: 0

conversionsnumberrequired#

The number of leads that converted to paying customers.

Default: 0

salesnumberrequired#

The total number of sales (includes recurring sales) generated by the short link.

Default: 0

saleAmountnumberrequired#

The total dollar value of sales (in cents) generated by the short link.

Default: 0

lastClickedstringrequired#

createdAtstringrequired#

updatedAtstringrequired#

tagIdstringrequireddeprecated#

Deprecated: Use tags instead. The unique ID of the tag assigned to the short link.

projectIdstringrequireddeprecated#

Deprecated: Use workspaceId instead. The project ID of the short link.

webhookIdsstring[]requireddeprecated#

customerobjectrequired#

Show child attributes

idstringrequired#

The unique ID of the customer. You may use either the customer's id on Dub (obtained via /customers endpoint) or their externalId (unique ID within your system, prefixed with ext_, e.g. ext_123).

namestring#

Name of the customer.

emailstring#

Email of the customer.

avatarstring#

Avatar URL of the customer.

externalIdstringrequired#

Unique identifier for the customer in the client's app.

stripeCustomerIdstring#

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

countrystring#

Country of the customer.

salesnumber#

Total number of sales for the customer.

saleAmountnumber#

Total amount of sales for the customer.

createdAtstringrequired#

The date the customer was created (usually the signup date or trial start date).

firstSaleAtstring#

The date the customer made their first sale. Useful for calculating the time to first sale and LTV.

subscriptionCanceledAtstring#

The date the customer canceled their subscription. Useful for calculating LTV and churn rate.

click_idstringrequireddeprecated#

Deprecated: Use click.id instead.

link_idstringrequireddeprecated#

Deprecated: Use link.id instead.

domainstringrequireddeprecated#

Deprecated: Use link.domain instead.

keystringrequireddeprecated#

Deprecated: Use link.key instead.

urlstringrequireddeprecated#

Deprecated: Use click.url instead.

continentstringrequireddeprecated#

Deprecated: Use click.continent instead.

countrystringrequireddeprecated#

Deprecated: Use click.country instead.

citystringrequireddeprecated#

Deprecated: Use click.city instead.

devicestringrequireddeprecated#

Deprecated: Use click.device instead.

browserstringrequireddeprecated#

Deprecated: Use click.browser instead.

osstringrequireddeprecated#

Deprecated: Use click.os instead.

qrnumberrequireddeprecated#

Deprecated: Use click.qr instead.

ipstringrequireddeprecated#

Deprecated: Use click.ip instead.

eventenum<string>required#

Options:sale

timestampstringrequired#

eventIdstringrequired#

eventNamestringrequired#

saleobjectrequired#

Show child attributes

amountintegerrequired#

The amount of the sale in cents (for all two-decimal currencies). If the sale is in a zero-decimal currency, pass the full integer value (e.g. 1580 JPY). Learn more: https://d.to/currency

Range: 0–9007199254740991

invoiceIdstringrequired#

The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID.

Default: null

paymentProcessorenum<string>required#

The payment processor via which the sale was made.

Default: "custom"

Options:stripeshopifypolarpaddleapplerevenuecatlemonsqueezydubcustom

currencyanyrequired#

The currency of the sale. Accepts ISO 4217 currency codes. Sales will be automatically converted and stored as USD at the latest exchange rates. Learn more: https://d.to/currency

metadataany#

linkobjectrequired#

Show child attributes

idstringrequired#

The unique ID of the short link.

domainstringrequired#

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

keystringrequired#

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

urlstringrequired#

trackConversionbooleanrequired#

externalIdstringrequired#

tenantIdstringrequired#

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.

programIdstringrequired#

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

partnerIdstringrequired#

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

archivedbooleanrequired#

expiresAtstringrequired#

expiredUrlstringrequired#

disabledAtstringrequired#

passwordstringrequired#

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

proxybooleanrequired#

titlestringrequired#

The title of the short link. Will be used for Custom Link Previews if proxy is true.

descriptionstringrequired#

The description of the short link. Will be used for Custom Link Previews if proxy is true.

imagestringrequired#

The image of the short link. Will be used for Custom Link Previews if proxy is true.

videostringrequired#

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

rewritebooleanrequired#

doIndexbooleanrequired#

iosstringrequired#

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

androidstringrequired#

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

geoobjectrequired#

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

Show child attributes

{key}string#

publicStatsbooleanrequired#

tagsobject[]required#

The tags assigned to the short link.

Show child attributes

idstringrequired#

The unique ID of the tag.

namestringrequired#

The name of the tag.

colorenum<string>required#

The color of the tag.

Options:redyellowgreenbluepurplebrowngraypink

folderIdstringrequired#

The unique ID of the folder assigned to the short link.

commentsstringrequired#

The comments for the short link.

shortLinkstringrequired#

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

qrCodestringrequired#

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

utm_sourcestringrequired#

The UTM source of the short link.

utm_mediumstringrequired#

The UTM medium of the short link.

utm_campaignstringrequired#

The UTM campaign of the short link.

utm_termstringrequired#

The UTM term of the short link.

utm_contentstringrequired#

The UTM content of the short link.

testVariantsobject[]#

An array of A/B test URLs and the percentage of traffic to send to each URL.

Items: 2–4

Show child attributes

urlstringrequired#

percentagenumberrequired#

Range: 10–90

testStartedAtstringrequired#

testCompletedAtstringrequired#

userIdstringrequired#

workspaceIdstringrequired#

The workspace ID of the short link.

clicksnumberrequired#

The number of clicks on the short link.

Default: 0

leadsnumberrequired#

The number of leads the short link has generated.

Default: 0

conversionsnumberrequired#

The number of leads that converted to paying customers.

Default: 0

salesnumberrequired#

The total number of sales (includes recurring sales) generated by the short link.

Default: 0

saleAmountnumberrequired#

The total dollar value of sales (in cents) generated by the short link.

Default: 0

lastClickedstringrequired#

createdAtstringrequired#

updatedAtstringrequired#

tagIdstringrequireddeprecated#

Deprecated: Use tags instead. The unique ID of the tag assigned to the short link.

projectIdstringrequireddeprecated#

Deprecated: Use workspaceId instead. The project ID of the short link.

webhookIdsstring[]requireddeprecated#

clickobjectrequired#

Show child attributes

idstringrequired#

timestampstringrequired#

urlstringrequired#

countrystringrequired#

citystringrequired#

regionstringrequired#

continentstringrequired#

devicestringrequired#

browserstringrequired#

osstringrequired#

uastring#

triggerstring#

refererstringrequired#

refererUrlstringrequired#

qrbooleanrequired#

ipstringrequired#

customerobjectrequired#

Show child attributes

idstringrequired#

namestring#

Name of the customer.

emailstring#

Email of the customer.

avatarstring#

Avatar URL of the customer.

externalIdstringrequired#

Unique identifier for the customer in the client's app.

stripeCustomerIdstring#

The customer's Stripe customer ID. This is useful for attributing recurring sale events to the partner who referred the customer.

countrystring#

Country of the customer.

salesnumber#

Total number of sales for the customer.

saleAmountnumber#

Total amount of sales for the customer.

createdAtstringrequired#

The date the customer was created (usually the signup date or trial start date).

firstSaleAtstring#

The date the customer made their first sale. Useful for calculating the time to first sale and LTV.

subscriptionCanceledAtstring#

The date the customer canceled their subscription. Useful for calculating LTV and churn rate.

saleAmountnumberrequireddeprecated#

Deprecated: Use sale.amount instead.

invoice_idstringrequireddeprecated#

Deprecated: Use sale.invoiceId instead.

payment_processorstringrequireddeprecated#

Deprecated: Use sale.paymentProcessor instead.

click_idstringrequireddeprecated#

Deprecated: Use click.id instead.

link_idstringrequireddeprecated#

Deprecated: Use link.id instead.

domainstringrequireddeprecated#

Deprecated: Use link.domain instead.

keystringrequireddeprecated#

Deprecated: Use link.key instead.

urlstringrequireddeprecated#

Deprecated: Use click.url instead.

continentstringrequireddeprecated#

Deprecated: Use click.continent instead.

countrystringrequireddeprecated#

Deprecated: Use click.country instead.

citystringrequireddeprecated#

Deprecated: Use click.city instead.

devicestringrequireddeprecated#

Deprecated: Use click.device instead.

browserstringrequireddeprecated#

Deprecated: Use click.browser instead.

osstringrequireddeprecated#

Deprecated: Use click.os instead.

qrnumberrequireddeprecated#

Deprecated: Use click.qr instead.

ipstringrequireddeprecated#

Deprecated: Use click.ip instead.

Retrieve analytics Track a lead event