API reference

Analytics

The same click data as your dashboard: totals, unique visitors, devices, operating systems, browsers, countries, referrers, UTM campaigns, and a daily series.

What a click measures

A click is a request to your short link. Known bots and link-preview fetchers are recorded but excluded from every figure here. A click doesn’t prove that the app opened, or that someone installed, subscribed, or purchased. Use your destination’s analytics for those outcomes. Smart Link forwards utm_* parameters to help. See how app opening works for more detail.

Choosing a range

Both endpoints accept the same range parameters. A range can span at most 366 days. Longer or reversed ranges return 400 VALIDATION_ERROR. All buckets use UTC.

Range parameters
Name	Type	Description
days	integer	Look back this many days, 1-366. Default 30.
from	string (ISO 8601)	Start of the range. When set, days is ignored.
to	string (ISO 8601)	End of the range. Default now. A date like 2026-09-30 includes that whole day (UTC).

totalClicks, clicksToday, clicksThisWeek, and clicksThisMonth are fixed windows and ignore the range. Everything else, including the breakdown percentages, is relative to clicksInPeriod.

Analytics for one link

GET/api/v1/links/{id}/analytics

curl

curl "https://smartlink.sh/api/v1/links/cm1x2y3z4000008l1abcd1234/analytics?days=7" \
  -H "Authorization: Bearer $SMARTLINK_API_KEY"

# Or an explicit window (a date-only "to" includes that whole day)
curl "https://smartlink.sh/api/v1/links/cm1x2y3z4000008l1abcd1234/analytics?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $SMARTLINK_API_KEY"

Response

{
  "data": {
    "range": { "from": "2026-09-22T12:00:00.000Z", "to": "2026-09-29T12:00:00.000Z" },
    "url": { "id": "cm1x2y3z4000008l1abcd1234", "shortCode": "launch", "platform": "TIKTOK", … },
    "totalClicks": 1480,
    "clicksToday": 36,
    "clicksThisWeek": 402,
    "clicksThisMonth": 1311,
    "clicksInPeriod": 402,
    "uniqueVisitors": 351,
    "deviceBreakdown": [{ "device": "MOBILE", "clicks": 344, "percentage": 85.57 }],
    "osBreakdown": [{ "os": "iOS", "clicks": 211, "percentage": 52.49 }],
    "browserBreakdown": [{ "browser": "Safari", "clicks": 120, "percentage": 29.85 }],
    "countryBreakdown": [{ "country": "Germany", "clicks": 97, "percentage": 24.13 }],
    "referrerBreakdown": [{ "referrer": "instagram.com", "clicks": 150, "percentage": 37.31 }],
    "campaignBreakdown": [{ "source": "newsletter", "clicks": 60, "percentage": 14.93 }],
    "clicksByDay": [{ "date": "2026-09-22", "clicks": 51 }, …],
    "clicksByHour": [{ "hour": "2026-09-29T11:00:00.000Z", "clicks": 4 }, …],
    "recentClicks": [{ "id": "…", "device": "MOBILE", "os": "Android", "country": "Brazil", "createdAt": "…" }, …]
  }
}

clicksByHour always covers the last 24 hours. Breakdowns list the top 10 values.

Analytics across all links

GET/api/v1/analytics

Returns the same fields as above without url and clicksByHour. It adds totalUrls, activeUrls, and topUrls, which lists your 10 most-clicked links in the range.

curl "https://smartlink.sh/api/v1/analytics?days=30" \
  -H "Authorization: Bearer $SMARTLINK_API_KEY"