Skip to content

Analytics

Availability: The analytics API is available on every plan, including Free. Keys need analytics:read, and calls count toward the analytics rate limit.

The analytics API returns a link’s click totals: all clicks, unique visitors, and clicks by country. For breakdowns by date, referrer, device and more, use the dashboards; for leads, sales and revenue, use the conversions API.

Analytics endpoints have their own, lower per-minute limit; see rate limits.

Endpoints

MethodPathScope
GET/api/v1/analytics/links/{public_id}analytics:read

Get a link’s clicks

GET /api/v1/analytics/links/{public_id} returns the totals for one link, by its public_id.

curl https://app.shortn.link/api/v1/analytics/links/3f6c1e2a-9b8d-4c7e-a1f0-5d2e3c4b6a71 \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "total_clicks": 1280,
  "unique_clicks": 941,
  "clicks_by_country": {
    "Germany": 512,
    "Czechia": 430,
    "United States": 301,
    "Unknown": 37
  }
}
FieldDescription
total_clicksAll of the link’s recorded clicks. Crawlers, such as link-preview bots, aren’t counted.
unique_clicksUnique visitors among those clicks.
clicks_by_countryClicks per country, by country name. Clicks whose country couldn’t be told are under Unknown. The values add up to total_clicks.

The totals cover the link’s whole history, not a date range.

Freshness

New clicks can take a moment to reach analytics. Responses say how complete the data is:

  • X-Analytics-As-Of is current when every click is included. Otherwise it’s the time (RFC 3339, UTC) up to which clicks are complete.
  • When analytics can’t be read, the response is 503 with X-Analytics-Unavailable: 1. Retry shortly.

Errors

StatusCode or errorMeaning
403api_key_workspace_mismatchThe link isn’t in the key’s workspace.
404link_not_foundNo link with this public_id, or the key can’t see it.
429api_rate_limit_exceededOver the analytics rate limit.
503Failed to get analyticsAnalytics are temporarily unavailable.

The anonymous links made on shortn.link have a public preview that needs no key; see public endpoints.

Last updated on