Real-Time Telemetry & Metrics API

Extract rich audience analytics, geographic breakdown, device statistics, and click telemetry with millisecond precision.

4 min read•Official Edge Documentation

Overview & Architecture

Every interaction with your short links produces instant metrics aggregated at the Edge. No personally identifiable information (PII) is stored, ensuring native GDPR, CCPA, and PECR compliance.

Redirection counters (count) and financial conversion amounts (amount) synchronize in real time via REST API to power live dashboards, automation alerts, or financial profitability tracking systems (ROI/EPC).

Key Principles

Core architectural pillars ensuring high performance, isolation, and security.

01Atomic Click Counters (Count)

Every click is counted atomically at the Edge (totalClicks) and split between raw volume and cookieless unique visitors (uniqueVisitors).

02Monetary Metrics & Revenue (Amount)

Track cumulative revenue (trackedRevenue), average order value (AOV), and earnings per click (EPC = total revenue / total clicks).

03Multi-Dimensional Segmentation

Analyze performance by country, continent, device type (mobile, desktop, tablet), OS, and browser.

04Referrer Tracking

Pinpoint exact traffic sources (Twitter/X, LinkedIn, newsletters, search engines).

SDK Integration

Implementation & SDK Examples

Ready-to-use TypeScript code snippets and configuration examples for your integrations.

1. Fetching Statistics via SDK

Query comprehensive metrics for a specific link:

get-analytics.ts

typescript

123456789
import { lshorter } from "@/lib/lshorter";
 
const stats = await lshorter.analytics.get("launch-2026", {
  period: "30d", // 24h, 7d, 30d, 90d, all
});
 
console.log("Total Clicks:", stats.totalClicks);
console.log("Top Countries:", stats.topCountries);
console.log("Device Breakdown:", stats.devices);

REST API Specification

API Endpoints & Reference

Direct HTTP request methods, parameters schema, authentication, and responses.

GET

Get Link Analytics

Bearer <API_KEY>60 to 1,400 req/min (by plan)

https://lsho.cc/api/v1/analytics/:slug

Retrieves aggregated click telemetry, country distribution, device breakdown, browser statistics, and top referring sources for a specific short link.

Path Parameters

Parameter	Type	Required	Description	Example
slug	string	Required	Short link slug alias.	`launch-2026`

Query Parameters

Parameter	Type	Required	Description	Example
period	string (24h \| 7d \| 30d \| 90d \| all)	Optional	Timeframe window for metrics aggregation.Default: `30d`	`30d`
country	string (ISO 3166-1 alpha-2)	Optional	Filter statistics by a specific country code.	`US`
device	string (mobile \| desktop \| tablet)	Optional	Filter statistics by device type.	`mobile`

Request Examples

bash

12
curl -X GET "https://lsho.cc/api/v1/analytics/launch-2026?period=30d" \
  -H "Authorization: Bearer $LSHORTER_API_KEY"

Response Payload

200 OKTelemetry payload containing comprehensive traffic analysis.

response-200.json

json

123456789101112131415161718192021222324252627282930313233
{
  "slug": "launch-2026",
  "period": "30d",
  "totalClicks": 3482,
  "uniqueVisitors": 2910,
  "conversionsCount": 87,
  "conversionRate": 2.5,
  "trackedRevenue": 4263.0,
  "currency": "USD",
  "epc": 1.22,
  "averageOrderValue": 49.0,
  "topCountries": [
    { "code": "US", "name": "United States", "clicks": 1420, "percentage": 40.7 },
    { "code": "GB", "name": "United Kingdom", "clicks": 890, "percentage": 25.5 },
    { "code": "DE", "name": "Germany", "clicks": 450, "percentage": 12.9 },
    { "code": "FR", "name": "France", "clicks": 310, "percentage": 8.9 }
  ],
  "devices": {
    "mobile": 2180,
    "desktop": 1150,
    "tablet": 152
  },
  "browsers": [
    { "name": "Chrome", "clicks": 1940 },
    { "name": "Safari", "clicks": 1120 },
    { "name": "Firefox", "clicks": 422 }
  ],
  "referrers": [
    { "source": "t.co", "clicks": 1200 },
    { "source": "linkedin.com", "clicks": 840 },
    { "source": "direct", "clicks": 950 }
  ]
}

Recommended Best Practices

Expert tips to maximize performance, resilience, and link security.

Recommendation 01

Use the period query parameter to fetch exact time windows for automated weekly and monthly campaign reporting.

Recommendation 02

Leverage mobile vs desktop breakdown to fine-tune your target page responsive design and load speed.

Recommendation 03

Combine UTM parameters with the referrer telemetry to isolate paid ad performance from organic social traffic.

Previous guideAdvanced Security & PIN Code Protection Next guideClick Limits & Scheduled Expiration

Related Guides & APIs

Overview & Architecture

Every interaction with your short links produces instant metrics aggregated at the Edge. No personally identifiable information (PII) is stored, ensuring native GDPR, CCPA, and PECR compliance.

123456789

import { lshorter } from "@/lib/lshorter"; const stats = await lshorter.analytics.get("launch-2026", { period: "30d", // 24h, 7d, 30d, 90d, all }); console.log("Total Clicks:", stats.totalClicks); console.log("Top Countries:", stats.topCountries); console.log("Device Breakdown:", stats.devices);

Parameter

Type

Required

Description

Example

slug

string

Required

Short link slug alias.

launch-2026

Parameter

Type

Required

Description

Example

period

string (24h | 7d | 30d | 90d | all)

Optional

Timeframe window for metrics aggregation.Default: 30d

30d

country

string (ISO 3166-1 alpha-2)

Optional

Filter statistics by a specific country code.

US

device

string (mobile | desktop | tablet)

Optional

Filter statistics by device type.

mobile

123456789101112131415161718192021222324252627282930313233

{ "slug": "launch-2026", "period": "30d", "totalClicks": 3482, "uniqueVisitors": 2910, "conversionsCount": 87, "conversionRate": 2.5, "trackedRevenue": 4263.0, "currency": "USD", "epc": 1.22, "averageOrderValue": 49.0, "topCountries": [ { "code": "US", "name": "United States", "clicks": 1420, "percentage": 40.7 }, { "code": "GB", "name": "United Kingdom", "clicks": 890, "percentage": 25.5 }, { "code": "DE", "name": "Germany", "clicks": 450, "percentage": 12.9 }, { "code": "FR", "name": "France", "clicks": 310, "percentage": 8.9 } ], "devices": { "mobile": 2180, "desktop": 1150, "tablet": 152 }, "browsers": [ { "name": "Chrome", "clicks": 1940 }, { "name": "Safari", "clicks": 1120 }, { "name": "Firefox", "clicks": 422 } ], "referrers": [ { "source": "t.co", "clicks": 1200 }, { "source": "linkedin.com", "clicks": 840 }, { "source": "direct", "clicks": 950 } ] }