API Reference
Analytics
Retrieve click analytics and traffic data for your links.
Get link analytics
GET/api/v1/links/:slug/analytics
Returns aggregated analytics for a specific link over a given time period.
Scope: read
Query parameters
period
"7d" | "30d" | "90d"=
"7d"Time window for analytics data.
Request
curl "https://shorten.dev/api/v1/links/x7kQ2m/analytics?period=30d" \
-H "Authorization: Bearer sk_..."const res = await fetch(
"https://shorten.dev/api/v1/links/x7kQ2m/analytics?period=30d",
{ headers: { Authorization: "Bearer sk_..." } }
);
const analytics = await res.json();
console.log(`${analytics.total_clicks} clicks, ${analytics.unique_visitors} unique`);const analytics = await shorten.analytics.get("x7kQ2m", { period: "30d" });
console.log(`${analytics.total_clicks} clicks, ${analytics.unique_visitors} unique`);Response — 200 OK
{
"slug": "x7kQ2m",
"period": "30d",
"total_clicks": 12847,
"unique_visitors": 8234,
"time_series": [
{ "date": "2026-01-17", "clicks": 423 },
{ "date": "2026-01-18", "clicks": 512 }
],
"top_referrers": [
{ "referrer": "google.com", "count": 4521 },
{ "referrer": "twitter.com", "count": 2103 },
{ "referrer": "direct", "count": 1876 }
],
"top_countries": [
{ "country": "US", "count": 5423 },
{ "country": "GB", "count": 1876 }
],
"top_devices": [
{ "device": "desktop", "count": 7981 },
{ "device": "mobile", "count": 3989 },
{ "device": "tablet", "count": 877 }
],
"top_browsers": [
{ "browser": "Chrome", "count": 7234 },
{ "browser": "Safari", "count": 2876 },
{ "browser": "Firefox", "count": 1543 }
]
}Response fields
slug
string
The link slug these analytics belong to.
period
string
The requested time period.
total_clicks
integer
Total click count within the period.
unique_visitors
integer
Unique visitors within the period, determined by IP hash.
time_series
object[]
Daily click counts. Each entry contains a `date` (YYYY-MM-DD) and `clicks` count.
top_referrers
object[]
Top 10 traffic sources. Each entry contains a `referrer` string and `count`. Direct traffic is reported as `"direct"`.
top_countries
object[]
Top 10 countries by ISO 3166-1 alpha-2 code with `count`.
top_devices
object[]
Top 10 device categories (`desktop`, `mobile`, `tablet`) with `count`.
top_browsers
object[]
Top 10 browsers by name with `count`.
Analytics are eventually consistent with approximately a 1-hour delay from click to aggregated data.
Errors
| Status | Code | When |
|---|---|---|
404 | not_found | Link not found or not owned by the authenticated user |