Analytics API
Read your workspace's link analytics from your backend, and report visits to a redirect you run yourself so they appear in the same numbers. Both routes require a server key; publishable keys are refused.
Query analytics
GET /v1/server/analytics answers one question at a time: one grouping over a time range in a time zone, narrowed by any filters. The console's Analytics page sends the same query.
curl --fail-with-body \
'https://api.linkrunway.com/v1/server/analytics?groupBy=countries&interval=30d&timezone=America/Chicago&device=Mobile' \
-H "Authorization: Bearer $LINKRUNWAY_SERVER_KEY"| Parameter | Values |
|---|---|
groupBy | count (default), timeseries, continents, countries, regions, cities, devices, browsers, os, triggers, languages, referers, referer_urls, top_links, top_urls, top_partners, utm_sources, utm_mediums, utm_campaigns, utm_terms, utm_contents |
event | composite (default), clicks, leads or sales: the metric a grouping is ranked by. Every row carries all three |
interval | 24h, 7d, 30d (default), 90d, mtd, qtd, ytd, 1y or all |
start, end | Instead of an interval: calendar days such as 2026-11-01 (both inclusive) or ISO 8601 timestamps with an offset |
timezone | An IANA time zone, default UTC. Day and month boundaries and series labels follow it |
limit | Rows for a grouping, 1 to 1,000 (default 100) |
format | json (default) or csv |
count returns totals with clicks, leads, sales, saleAmount and uniqueVisitors. timeseries returns series, one point per hour, day or month (by the length of the range) with every empty bucket included. Every other grouping returns ranked rows with a value (null when unknown) and the same metrics; places also carry country and region, and top_links carries the link's shortUrl.
Clicks are human link visits; bots and visits flagged as fraud are excluded. Leads are SIGNUP events and sales are verified PURCHASE and SUBSCRIPTION events credited to those visits. saleAmount holds verified sales less refunds in integer minor units, per currency.
Filters
Every filter narrows the whole answer. link, partner, domain, tag, continent, country, device, browser, os, trigger and language accept comma-separated values. region, city, referer, refererUrl, url, utmSource, utmMedium, utmCampaign, utmTerm and utmContent accept one value per repeated parameter. Prefix a value with ! to exclude it, and use (none) for a missing value: referer=(none) is direct traffic and referer=!(none) is everything else. Values of one filter are alternatives; separate filters must all match.
Places come from the visitor's address, which is never stored. IP Geolocation by DB-IP.
Report visits from your own redirect
When your own server redirects visitors, report each visit with POST /v1/server/clicks. It is recorded like a visit to a LinkRunway short link and counts toward your plan's click allowance.
curl --fail-with-body https://api.linkrunway.com/v1/server/clicks \
-H "Authorization: Bearer $LINKRUNWAY_SERVER_KEY" \
-H 'Content-Type: application/json' \
--data '{"linkId":"LINK_ID","externalId":"visit-789","ip":"203.0.113.7","userAgent":"Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)","referrer":"https://www.example.com/post","url":"https://go.example.com/spring?utm_source=newsletter"}'| Field | Notes |
|---|---|
linkId | A link in your workspace |
externalId | Your identifier for the visit: letters, digits and _.:-, at most 200 characters |
occurredAt | Optional ISO 8601 time of the visit, within the last seven days |
ip | Optional visitor address, used to place the visit and estimate unique visitors; not stored |
userAgent | Optional visitor user agent |
referrer | Optional referring page |
acceptLanguage | Optional Accept-Language header |
url | Optional address the visitor opened; its utm_* tags and qr=1 are recorded |
destination | Optional address the visitor was sent to |
country | Optional two-letter country when your edge knows it better than the address |
privacy | true when the visitor sent Global Privacy Control or Do Not Track |
The response carries clickId, duplicate and, for an attributable visit, a clickToken. Reporting the same externalId again returns the first click with duplicate: true. A later server-key event can name the visit with clickExternalId instead of a click token; see events.