Retrieve analytics

Retrieve analytics for a link, a domain, or the authenticated workspace. The response type depends on the event and type query parameters.

GET /analytics

Go

Go

package main

import(
	"context"
	dubgo "github.com/dubinc/dub-go"
	"github.com/dubinc/dub-go/models/operations"
	"log"
)

func main() {
    ctx := context.Background()

    s := dubgo.New(
        dubgo.WithSecurity("DUB_API_KEY"),
    )

    res, err := s.Analytics.Retrieve(ctx, operations.RetrieveAnalyticsRequest{
        Event: operations.EventLeads.ToPointer(),
        Domain: dubgo.Pointer("dub.co"),
        Timezone: dubgo.Pointer("America/New_York"),
        City: dubgo.Pointer("New York"),
        Device: dubgo.Pointer("Desktop"),
        Browser: dubgo.Pointer("Chrome"),
        Os: dubgo.Pointer("Windows"),
        Referer: dubgo.Pointer("google.com"),
        RefererURL: dubgo.Pointer("https://dub.co/blog"),
        Query: dubgo.Pointer("metadata['key']:'value'"),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // handle response
    }
}

200

{
  "clicks": 0,
  "leads": 0,
  "sales": 0,
  "saleAmount": 0
}

Analytics endpoints require a Pro 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, composite

Example:

"leads"

groupBy · enum<string> · default: count

The parameter to group the analytics data points by. Defaults to count if undefined.

Available options: 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, utm_sources, utm_mediums, utm_campaigns, utm_terms, utm_contents

domain · string

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"

key · string

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.

linkId · string

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.

externalId · string

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. Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with -). Examples: tenant_123, tenant_123,tenant_456, -tenant_789.

tagId · string

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.

folderId · string

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.

groupId · string

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.

partnerId · string

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.

customerId · string

The ID of the customer to retrieve analytics for.

interval · enum<string>

The interval to retrieve analytics for. 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. If set, takes precedence over interval.

end · string

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.

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 · string

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.

city · string

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.

region · string

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.

continent · string

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.

device · string

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

browser · string

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.

os · string

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.

trigger · string

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.

referer · string

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.

refererUrl · string

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.

url · string

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_source · string

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_medium · string

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_campaign · string

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_term · string

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

utm_content · string

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

root · boolean

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

saleType · enum<string>

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

Available options: new, recurring

query · string

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

Maximum string length: 10000

programId · string · deprecated

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

tagIds · string · deprecated

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

qr · boolean · deprecated

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

Response

200

application/json

Analytics data

Option 1 · object

Option 2 · object[]

Option 3 · object[]

Option 4 · object[]

Option 5 · object[]

Option 6 · object[]

Option 7 · object[]

Option 8 · object[]

Option 9 · object[]

Option 10 · object[]

Option 11 · object[]

Option 12 · object[]

Option 13 · object[]

Option 14 · object[]

clicks · number · default: 0 · required

The total number of clicks

leads · number · default: 0 · required

The total number of leads

sales · number · default: 0 · required

The total number of sales

saleAmount · number · default: 0 · required

The total amount of sales, in cents