Analytics API

Base URL: https://qck.sh/public-api/v1

All endpoints require analytics:read permission.

Response envelope

All analytics responses wrap data under analytics and include tier usage info:

{
  "success": true,
  "data": {
    "analytics": { ... },
    "usage": {
      "clicks_this_month": 4500,
      "click_limit": 5000,
      "limit_exceeded": false,
      "tier": "basic",
      "retention_days": 365
    }
  }
}

The click_limit is null for tiers with unlimited clicks. If limit_exceeded is true, date ranges are clamped to show only the most recent data within budget, and the usage object includes a cutoff_date field (YYYY-MM-DD), the earliest date queries are clamped to.

Common parameters

All analytics endpoints accept these query parameters:

Param	Type	Default	Description
`days`	integer	30	Rolling window (1–365)
`start_date`	string	None	Start date (YYYY-MM-DD), overrides `days`
`end_date`	string	None	End date (YYYY-MM-DD)
`bot_filter`	string	`real`	`real`, `bot`, or `all`
`domain_name`	string	None	Filter to a custom domain

Summary

GET /analytics/summary

{
  "success": true,
  "data": {
    "analytics": {
      "total_clicks": 12500,
      "unique_visitors": 8900,
      "total_links": 150,
      "last_click_at": "2026-04-08T10:30:00Z",
      "today_clicks": 320,
      "yesterday_clicks": 410,
      "active_links": 120,
      "total_links_count": 200,
      "links_this_month": 18,
      "clicks_this_month": 4500
    },
    "usage": { ... }
  }
}

Timeseries

GET /analytics/timeseries

Returns daily click data over time.

{
  "success": true,
  "data": {
    "analytics": [
      { "date": "2026-04-01", "clicks": 450, "unique_visitors": 320 },
      { "date": "2026-04-02", "clicks": 380, "unique_visitors": 290 }
    ],
    "usage": { ... }
  }
}

Geography

GET /analytics/geo

Clicks grouped by country.

{
  "success": true,
  "data": {
    "analytics": [
      { "country_code": "US", "clicks": 5200, "unique_visitors": 3800 },
      { "country_code": "DE", "clicks": 1100, "unique_visitors": 900 }
    ],
    "usage": { ... }
  }
}

Devices

GET /analytics/devices

Clicks by device type, browser, and OS.

{
  "success": true,
  "data": {
    "analytics": [
      { "device_type": "desktop", "browser": "Chrome", "os": "Windows", "clicks": 3200 },
      { "device_type": "mobile", "browser": "Safari", "os": "iOS", "clicks": 2100 }
    ],
    "usage": { ... }
  }
}

Referrers

GET /analytics/referrers

Traffic sources.

{
  "success": true,
  "data": {
    "analytics": [
      { "referrer": "google.com", "clicks": 2400, "unique_visitors": 1900 },
      { "referrer": "direct", "clicks": 1800, "unique_visitors": 1500 }
    ],
    "usage": { ... }
  }
}

Hourly

GET /analytics/hourly

Click distribution by hour of day (0–23 UTC).

{
  "success": true,
  "data": {
    "analytics": [
      { "hour": 9, "clicks": 520, "unique_visitors": 410 },
      { "hour": 14, "clicks": 680, "unique_visitors": 490 }
    ],
    "usage": { ... }
  }
}