Analytics API
One request returns the full click report for a short link: lifetime and 30 day totals, where clicks came from, which devices they used, UTM values, and the latest individual clicks. It is the same report the link page in the dashboard shows, as JSON you can feed into a spreadsheet, a BI tool or a weekly email.
GET /api/v1/stats/:code
Pass the link's short code in the path, for example spring-sale for go.example.com/spring-sale. The key needs both analytics:read and links:read, because the report includes the destination URL as well as the counts. See authentication for headers and scopes.
curl https://trimlink.co/api/v1/stats/spring-sale \
-H "X-API-Key: tk_live_your_api_key"The endpoint takes no query parameters. Every response covers a fixed window: the last 30 days, by day. A few totals are lifetime numbers instead, and the field tables below say which.
Response (trimmed)
Arrays are cut to one or two items here, and some link fields are left out. A real response always carries every field listed below.
{
"success": true,
"data": {
"linkId": "9c8b7a6d-5e4f-4a3b-8291-0d1e2f3a4b5c",
"entitlementTier": "pro",
"shortCode": "spring-sale",
"originalUrl": "https://example.com/spring?utm_source=newsletter",
"title": "Spring sale",
"description": null,
"customDomain": "go.example.com",
"createdAt": "2026-10-02T09:14:00.000Z",
"expiresAt": null,
"isPaused": false,
"isTrackingPaused": false,
"totalClicks": 1542,
"rangeClicks": 618,
"last7": 131,
"clicksDelta": 12,
"uniqueVisitors": {
"totalClicks": 618,
"estimatedUniqueVisitors": 402,
"accuracy": "±2%",
"method": "hyperloglog"
},
"qrScanCount": 214,
"distinctCountries": 23,
"clicksByDevice": [
{ "device": "mobile", "count": 402 },
{ "device": "desktop", "count": 197 }
],
"clicksByCountry": [
{ "country": "US", "count": 233 },
{ "country": "GB", "count": 96 }
],
"clicksByReferrer": [{ "referrer": "www.linkedin.com", "count": 141 }],
"clicksByUtmSource": [{ "source": "newsletter", "count": 288 }],
"clicksBySource": [
{ "source": "direct", "count": 520 },
{ "source": "qr", "count": 98 }
],
"recentClicks": [
{ "date": "2026-10-21", "count": 0 },
{ "date": "2026-10-22", "count": 17 }
],
"range": { "token": "30d", "label": "Last 30 days", "granularity": "day" },
"busiestDay": { "date": "2026-11-03", "count": 64 },
"peakHour": { "hour": 14, "count": 188 },
"velocity": { "last24h": 21, "prior24h": 15, "verdict": "hot" },
"recentActivity": [
{
"countryCode": "US",
"deviceType": "mobile",
"clickSource": "qr",
"clickedAt": "2026-11-19T08:02:11.000Z"
}
],
"comparison": {
"rank": 2,
"totalLinks": 37,
"percentile": 97,
"avgClicks": 210,
"vsAvgPct": 634
}
}
}Link details
Who the report is about. These fields are why the endpoint also needs links:read.
| Field | Type | Meaning |
|---|---|---|
linkId | string | The link id. |
shortCode | string | The short code you asked for. |
originalUrl | string | The destination URL, query string included. |
title, description | string or null | Labels set on the link. |
customDomain | string or null | The branded host, such as go.example.com, when the link uses one. |
createdAt, expiresAt | ISO date or null | When the link was made and when it expires, if ever. |
isPaused, pauseReason, pausedAt | boolean, string or null | Whether the link stopped redirecting, why, and since when. |
isTrackingPaused, trackingPauseReason, trackingPausedAt | boolean, string or null | The link still redirects but stopped counting clicks, for example after the monthly tracked click allowance ran out. |
entitlementTier | string | The plan the report was built for, such as pro. |
qrCode | object or null | The saved QR code with its settings, scan count and download count. Its data field holds the whole image (base64 PNG or SVG markup), so expect a large payload. |
Totals
Headline numbers. Note which ones are lifetime and which cover the last 30 days.
| Field | Type | Meaning |
|---|---|---|
totalClicks | number | Lifetime clicks, unfiltered. |
rangeClicks | number | Clicks in the last 30 days. |
last7 | number | Clicks in the last 7 days. |
clicksDelta | number or null | Whole percent change, last 30 days against the 30 days before. null when that earlier window had no clicks. |
uniqueVisitors | object | estimatedUniqueVisitors plus the clicks it was estimated from, accuracy and method. See the note below. |
qrScanCount | number | Lifetime clicks that came from scanning the QR code. |
distinctCountries | number | Countries reached over the link lifetime. Not capped. |
Breakdowns (last 30 days)
Arrays of { name, count } pairs, busiest first. The name key matches the dimension, for example country.
| Field | Type | Meaning |
|---|---|---|
clicksByDevice | array | desktop, mobile, tablet or unknown. |
clicksByCountry | array | Top 10 countries as ISO 3166-1 alpha-2 codes. |
clicksByCity | array | Top 10 cities. Clicks from before May 2026 carry no city and are left out. |
clicksByRegion, clicksByContinent | array | Coarser geography from the same clicks. |
clicksByBrowser, clicksByOs | array | Browser and operating system family, no versions. |
clicksByReferrer | array | Top 10 referring hosts, with the path stripped. |
clicksBySocialReferrer, clicksBySearchReferrer | array | Referrers that are social networks or search engines, top 10 each. |
clicksByUtmSource, clicksByUtmMedium, clicksByUtmCampaign, clicksByUtmTerm, clicksByUtmContent | array | Clicks grouped by each UTM value recorded with the click. |
clicksBySource | array | How the click arrived: direct, qr or api. |
Time and activity
Shape of the traffic over time, plus the most recent individual clicks.
| Field | Type | Meaning |
|---|---|---|
recentClicks | array | 30 daily { date, count } points, oldest first. Days without clicks are 0, not missing. |
range | object | The window used. From the API it is always token 30d, label Last 30 days, granularity day. |
busiestDay | object or null | The day in the window with the most clicks. |
peakHour | object or null | The hour of day (0 to 23, UTC) with the most clicks over the link lifetime. |
velocity | object | Clicks in the last 24 hours and the 24 hours before, with a verdict: hot (up 25% or more, or clicks after a silent day), steady, cooling (down 25% or more) or quiet (none today). |
recentActivity | array | The 12 most recent clicks, newest first: country code, device type, source and time. Nothing else. |
sourceSplit | array | Lifetime clicks by source: direct, qr or api. |
comparison | object or null | Rank among your links by clicks, percentile, your average clicks per link, and this link against that average in percent. null when you have one link. |
How unique visitors are estimated
Click records hold no visitor id, no cookie and no IP address. To estimate unique visitors, TrimLink builds a throwaway signature for each click in the window from three coarse facts: country, device type and the hour of the click. It counts distinct signatures with HyperLogLog, which is where the ±2% accuracy figure comes from, and then discards them.
Two people in the same country on the same kind of device in the same hour count once, and one person who clicks in two different hours counts twice. Read estimatedUniqueVisitors as a rough audience size for trends, not as a head count.
What the report never contains
No IP addresses, no full user agent strings, no visitor ids and no exact locations. The most detailed fields are city names and the 12 most recent clicks, each reduced to country, device type, source and time. That is the same data the dashboard shows. Read more in URL shortener privacy.
Errors
Key problems come back as {"error": "..."} with the exact strings listed on the authentication page. A missing link uses the standard error format.
| Status | When it happens |
|---|---|
401 | No key, or the key is invalid, expired or revoked. |
403 | The key lacks analytics:read or links:read, or the account is no longer on Pro or above. |
404 | No link with that short code in the key owner’s personal workspace. |
429 | The account used its daily request budget. |
Usage notes
- API keys read links in their owner's personal workspace. A link that lives in a team workspace answers 404 to a key, even for a team member. Use the dashboard for team links.
- Every call costs one request from the account's daily budget, the same budget link creation uses. Polling once an hour per link is plenty for the daily breakdowns.
- If the link has a saved QR code,
qrCode.datacarries the full image. Strip it before you store reports. - When
isTrackingPausedis true the link still redirects, but new clicks are not counted, so totals stop growing until the monthly allowance resets or the plan is upgraded.
Plans and history
The API starts on Pro, and every report field is filled on Pro and above. The API always answers for the last 30 days. Longer history is viewable in the dashboard, up to your plan's limit.
| Plan | API requests | History you can view |
|---|---|---|
| Pro | 1,000 a day | 1 year |
| Growth | 10,000 a day | 2 years |
| Teams | Unlimited | Lifetime |
Compare plans on the pricing page, or learn which numbers matter in how to track link clicks.