Read click analytics

Goal: pull aggregated click counts for your links, grouped by a chosen dimension, over a date range.
Prerequisites: an API key (see Authentication).

Steps

1. Get clicks by country for a date range

curl -G https://api-sandbox.slimlinkdev.com/api/v1/analytics/clicks 
  -H "X-API-Key: <API_KEY>" 
  --data-urlencode "group_by=country" 
  --data-urlencode "start_date=2026-07-01" 
  --data-urlencode "end_date=2026-07-24"

Expected response:

{
  "data": {
    "group_by": "country",
    "items": [
      { "name": "United States", "count": 42, "unique_count": 38, "percentage": 60 },
      { "name": "Germany", "count": 28, "unique_count": 25, "percentage": 40 }
    ],
    "period": { "start_date": "2026-07-01T00:00:00Z", "end_date": "2026-07-24T00:00:00Z" },
    "pagination": { "page": 1, "per_page": 20 },
    "total_count": 70,
    "total_unique_count": 63
  },
  "error_code": null,
  "message": "Request successful"
}
curl -G https://api-sandbox.slimlinkdev.com/api/v1/analytics/clicks 
  -H "X-API-Key: <API_KEY>" 
  --data-urlencode "group_by=device" 
  --data-urlencode "link_id=06a447a7-5734-48b0-9dab-021576f0e0d1" 
  --data-urlencode "exclude_bots=true"

link_id, country, city, and device can each be repeated to filter by multiple values.

Verify

Check that total_count in the response matches the sum of count across items, and that period reflects the date range you requested.

Common failures

Symptom Cause Fix
400 validation error group_by missing or not one of the allowed values group_by is required — use one of link, country, city, os, device, browser, referrer.
401 Unauthorized Missing or invalid API key Confirm you’re sending X-API-Key.
Bot traffic inflating counts exclude_bots not set Pass exclude_bots=true.