Retrieve a list of events

Retrieve a paginated list of events for the authenticated workspace.

GET /events

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.Events.List(ctx, operations.ListEventsRequest{
        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

[
  {
    "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>",
      "trigger": "<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>",
      "webhookIds": [
        "<string>"
      ],
      "comments": "<string>",
      "shortLink": "<string>",
      "qrCode": "<string>",
      "utm_source": "<string>",
      "utm_medium": "<string>",
      "utm_campaign": "<string>",
      "utm_term": "<string>",
      "utm_content": "<string>",
      "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>",
      "testVariants": [
        {
          "url": "https://example.com/variant-1",
          "percentage": 50
        },
        {
          "url": "https://example.com/variant-2",
          "percentage": 50
        }
      ]
    },
    "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. 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.

page · number · default: 1

limit · number · default: 100

Required range: x <= 1000

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

ClickEvent

LeadEvent

SaleEvent

event · enum<string> · required

Available options: click

timestamp · string · required

click · object · required

Show child attributes

link · object · required

Show child attributes

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.