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.

200Response
{
  "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.

FieldTypeMeaning
linkIdstringThe link id.
shortCodestringThe short code you asked for.
originalUrlstringThe destination URL, query string included.
title, descriptionstring or nullLabels set on the link.
customDomainstring or nullThe branded host, such as go.example.com, when the link uses one.
createdAt, expiresAtISO date or nullWhen the link was made and when it expires, if ever.
isPaused, pauseReason, pausedAtboolean, string or nullWhether the link stopped redirecting, why, and since when.
isTrackingPaused, trackingPauseReason, trackingPausedAtboolean, string or nullThe link still redirects but stopped counting clicks, for example after the monthly tracked click allowance ran out.
entitlementTierstringThe plan the report was built for, such as pro.
qrCodeobject or nullThe 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.

FieldTypeMeaning
totalClicksnumberLifetime clicks, unfiltered.
rangeClicksnumberClicks in the last 30 days.
last7numberClicks in the last 7 days.
clicksDeltanumber or nullWhole percent change, last 30 days against the 30 days before. null when that earlier window had no clicks.
uniqueVisitorsobjectestimatedUniqueVisitors plus the clicks it was estimated from, accuracy and method. See the note below.
qrScanCountnumberLifetime clicks that came from scanning the QR code.
distinctCountriesnumberCountries 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.

FieldTypeMeaning
clicksByDevicearraydesktop, mobile, tablet or unknown.
clicksByCountryarrayTop 10 countries as ISO 3166-1 alpha-2 codes.
clicksByCityarrayTop 10 cities. Clicks from before May 2026 carry no city and are left out.
clicksByRegion, clicksByContinentarrayCoarser geography from the same clicks.
clicksByBrowser, clicksByOsarrayBrowser and operating system family, no versions.
clicksByReferrerarrayTop 10 referring hosts, with the path stripped.
clicksBySocialReferrer, clicksBySearchReferrerarrayReferrers that are social networks or search engines, top 10 each.
clicksByUtmSource, clicksByUtmMedium, clicksByUtmCampaign, clicksByUtmTerm, clicksByUtmContentarrayClicks grouped by each UTM value recorded with the click.
clicksBySourcearrayHow the click arrived: direct, qr or api.

Time and activity

Shape of the traffic over time, plus the most recent individual clicks.

FieldTypeMeaning
recentClicksarray30 daily { date, count } points, oldest first. Days without clicks are 0, not missing.
rangeobjectThe window used. From the API it is always token 30d, label Last 30 days, granularity day.
busiestDayobject or nullThe day in the window with the most clicks.
peakHourobject or nullThe hour of day (0 to 23, UTC) with the most clicks over the link lifetime.
velocityobjectClicks 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).
recentActivityarrayThe 12 most recent clicks, newest first: country code, device type, source and time. Nothing else.
sourceSplitarrayLifetime clicks by source: direct, qr or api.
comparisonobject or nullRank 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.

StatusWhen it happens
401No key, or the key is invalid, expired or revoked.
403The key lacks analytics:read or links:read, or the account is no longer on Pro or above.
404No link with that short code in the key owner’s personal workspace.
429The 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.data carries the full image. Strip it before you store reports.
  • When isTrackingPaused is 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.

PlanAPI requestsHistory you can view
Pro1,000 a day1 year
Growth10,000 a day2 years
TeamsUnlimitedLifetime

Compare plans on the pricing page, or learn which numbers matter in how to track link clicks.