Query click analytics for your shortened links using the same query API, with link_id instead of website_id.

External ID

Links support an optional external ID, a third-party identifier (e.g. company ID, campaign ID, partner ID) you can use to:

Filter invites: companies can tag invite links with their ID and list all links for that company
Attribute traffic: query which external entity drove clicks
Integrate: sync with your CRM, partner dashboard, or internal systems

Set externalId when creating or updating a link. Use externalId in the list endpoint to filter:

// Create link with external ID
{
"organizationId": "org_123",
"name": "Creator invite",
"targetUrl": "https://app.example.com/signup",
"externalId": "company_acme"
}

// List links filtered by external ID
{
"organizationId": "org_123",
"externalId": "company_acme"
}

Query link analytics

POST /v1/query?link_id={link_id}

Request body:

{
"parameters": ["link_total_clicks", "link_clicks_by_day", "link_top_referrers"],
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"granularity": "daily",
"limit": 10
}

Granularity

Time-series queries support hourly or daily granularity:

{
"parameters": ["link_clicks_by_day"],
"startDate": "2024-01-01",
"endDate": "2024-01-07",
"granularity": "hourly"
}

"daily": group by day (default)
"hourly": group by hour (max 30 day range)

When using hourly granularity, link_clicks_by_day returns data points for each hour instead of each day.

Available query types

Type	Description	Granularity
`link_total_clicks`	Total click count for the link	None
`link_clicks_by_day`	Time-series breakdown of clicks	hour, day
`link_referrers_by_day`	Time-series count of unique referrers	hour, day
`link_countries_by_day`	Time-series count of unique countries	hour, day
`link_top_referrers`	Top traffic sources	None
`link_top_countries`	Top countries by clicks	None
`link_top_regions`	Top regions by clicks	None
`link_top_cities`	Top cities by clicks	None
`link_top_devices`	Device type breakdown (mobile, desktop, tablet)	None
`link_top_browsers`	Browser breakdown	None

Example response

{
"success": true,
"queryId": "",
"data": [
  {
    "parameter": "link_total_clicks",
    "success": true,
    "data": [{ "total": 1542 }]
  },
  {
    "parameter": "link_clicks_by_day",
    "success": true,
    "data": [
      { "date": "2024-01-01", "clicks": 125 },
      { "date": "2024-01-02", "clicks": 143 }
    ]
  },
  {
    "parameter": "link_top_referrers",
    "success": true,
    "data": [
      { "name": "twitter.com", "referrer": "twitter.com", "clicks": 523 },
      { "name": "Direct", "referrer": "Direct", "clicks": 412 }
    ]
  }
],
"meta": {
  "parameters": ["link_total_clicks", "link_clicks_by_day", "link_top_referrers"],
  "total_parameters": 3,
  "page": 1,
  "limit": 10,
  "filters_applied": 0
}
}

Hourly response example

With "granularity": "hourly", time-series queries return data points for each hour:

{
"parameter": "link_clicks_by_day",
"success": true,
"data": [
  { "date": "2024-01-01 00:00:00", "clicks": 12 },
  { "date": "2024-01-01 01:00:00", "clicks": 8 },
  { "date": "2024-01-01 02:00:00", "clicks": 5 }
]
}

Outbound link tracking

For tracking which external links users click on your website (not link shortener), use these query types with website_id:

curl -X POST -H "x-api-key: dbdy_your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "parameters": ["outbound_links", "outbound_domains"],
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "limit": 20
}' \
"https://api.databuddy.cc/v1/query?website_id=web_123"

Outbound links response

{
"success": true,
"data": [
  {
    "parameter": "outbound_links",
    "success": true,
    "data": [
      {
        "href": "https://github.com/example/repo",
        "text": "View on GitHub",
        "total_clicks": 245,
        "unique_users": 189,
        "unique_sessions": 210,
        "percentage": 15.2,
        "last_clicked": "2024-01-31T15:42:00.000Z"
      }
    ]
  },
  {
    "parameter": "outbound_domains",
    "success": true,
    "data": [
      {
        "domain": "github.com",
        "total_clicks": 523,
        "unique_users": 412,
        "unique_links": 8,
        "percentage": 32.5
      }
    ]
  }
]
}

Differences: link shortener vs outbound links

Feature	Link shortener (`link_id`)	Outbound links (`website_id`)
Purpose	Clicks on your shortened URLs	Clicks on external links from your site
Query parameter	`link_id`	`website_id`
Query types	`link_*`	`outbound_links`, `outbound_domains`
Data source	Link redirect tracking	Website visitor tracking

For the dashboard workflow behind these endpoints, read the campaign links guide. The UTM tracking walkthrough explains how to verify website conversions separately from the click counts returned by link analytics.

Link analytics