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
| Method | Path | Scope |
|---|---|---|
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
}
}| Field | Description |
|---|---|
total_clicks | All of the link’s recorded clicks. Crawlers, such as link-preview bots, aren’t counted. |
unique_clicks | Unique visitors among those clicks. |
clicks_by_country | Clicks 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-Ofiscurrentwhen 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
503withX-Analytics-Unavailable: 1. Retry shortly.
Errors
| Status | Code or error | Meaning |
|---|---|---|
403 | api_key_workspace_mismatch | The link isn’t in the key’s workspace. |
404 | link_not_found | No link with this public_id, or the key can’t see it. |
429 | api_rate_limit_exceeded | Over the analytics rate limit. |
503 | Failed to get analytics | Analytics are temporarily unavailable. |
The anonymous links made on shortn.link have a public preview that needs no key; see public endpoints.
Last updated on