Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Andr21Da16/Quikko/llms.txt

Use this file to discover all available pages before exploring further.

Quikko records every redirect as a click event in InfluxDB. Each event captures the timestamp, short code, owning user ID, the visitor’s country (resolved via GeoIP), device type, and browser. Aggregated statistics — total clicks, breakdowns by country, device, and browser, plus a time-series chart — are available through a single API endpoint with three selectable time ranges. Free plan accounts are limited to the last 24 hours; Pro accounts can query up to 30 days of history.

​
What Gets Tracked Per Click

Every time a visitor follows a short link, the redirect handler captures the request and fires an async recording call. The following fields are written to InfluxDB as a clicks measurement:

Timestamp

The exact UTC time of the redirect, used as the InfluxDB series timestamp.

Short code

The shortCode identifier of the URL that was clicked — the primary tag for per-URL filtering.

User ID

The ownerID of the URL, enabling per-account aggregation without scanning all measurements.

Country

ISO 3166-1 alpha-2 country code resolved from the visitor’s IP via ipapi.co, cached in Redis for 48 hours.

Device type

Parsed from the User-Agent header: desktop, mobile, or tablet.

Browser

Browser family parsed from the User-Agent: Chrome, Firefox, Safari, Edge, and others.

​
GeoIP Resolution

Country lookup is performed by calling the external ipapi.co service. To avoid hitting the service on every redirect, results are cached in Redis with a 48-hour TTL. If the cache already holds a result for a given IP, no outbound HTTP request is made. If Redis is unavailable, the service degrades gracefully by querying ipapi.co directly.

​
Available Time Ranges

Pass the range query parameter to select the analysis window. An empty or omitted range defaults to 24h.
ValueWindowTime-series bucket size
24hLast 24 hours1-hour buckets
7dLast 7 days1-day buckets
30dLast 30 days1-day buckets
The 7d and 30d ranges are available on the Pro plan only. Free plan accounts that request these ranges receive a 403 PLAN_RANGE_NOT_ALLOWED response. The plan is checked on every request — upgrading takes effect immediately without requiring a re-login.

​
Stats Response Shape

The GET /api/v1/analytics/stats endpoint returns a StatsResponse envelope whose stats field matches the ClickStats schema: 
{
  "success": true,
  "data": {
    "range": "7d",
    "stats": {
      "totalClicks": 1482,
      "clicksByCountry": {
        "US": 620,
        "DE": 310,
        "BR": 198,
        "GB": 154,
        "other": 200
      },
      "clicksByDevice": {
        "mobile": 891,
        "desktop": 541,
        "tablet": 50
      },
      "clicksByBrowser": {
        "Chrome": 804,
        "Safari": 421,
        "Firefox": 180,
        "Edge": 77
      },
      "clicksOverTime": [
        { "timestamp": "2024-01-09T00:00:00Z", "count": 195 },
        { "timestamp": "2024-01-10T00:00:00Z", "count": 231 },
        { "timestamp": "2024-01-11T00:00:00Z", "count": 178 }
      ]
    }
  },
  "error": null
}
FieldTypeDescription
totalClicksint64Total click count across the selected time window
clicksByCountrymap[string]int64Per-country breakdown keyed by ISO 2-letter code
clicksByDevicemap[string]int64Per-device-type breakdown
clicksByBrowsermap[string]int64Per-browser breakdown
clicksOverTimeTimeBucket[]Ordered time-series array of {timestamp, count} buckets

​
Overview vs. Per-URL Stats

The same endpoint serves both all-URL and single-URL analytics depending on whether shortCode is present. All-URL overview — omit shortCode to aggregate across every URL you own: 
GET /api/v1/analytics/stats?range=7d
Single-URL stats — include shortCode to scope results to one link. The server validates ownership and returns 403 FORBIDDEN if the code belongs to another user or does not exist: 
GET /api/v1/analytics/stats?shortCode=aB3kR7m&range=7d

​
Fetching Stats — curl Examples

​
7-day stats for a specific URL

curl "https://quikko.io/api/v1/analytics/stats?shortCode=aB3kR7m&range=7d" \
  -H "Authorization: Bearer <accessToken>"

​
All-URL overview for the last 24 hours

curl "https://quikko.io/api/v1/analytics/stats?range=24h" \
  -H "Authorization: Bearer <accessToken>"

​
CSV Export

GET /api/v1/analytics/stats/export accepts the same shortCode and range parameters as the stats endpoint and applies identical ownership and plan-range validation. On success it returns a UTF-8 BOM CSV file (BOM prefix + CRLF line endings), which makes it directly openable in Microsoft Excel without an import wizard. The Content-Disposition header is set to attachment with a descriptive filename: 
Content-Disposition: attachment; filename="stats-aB3kR7m-7d.csv"

curl "https://quikko.io/api/v1/analytics/stats/export?shortCode=aB3kR7m&range=7d" \
  -H "Authorization: Bearer <accessToken>" \
  -o stats.csv
Error responses from the export endpoint — invalid range, forbidden URL, plan restriction — still use the standard JSON envelope, not a CSV body.

Build docs developers (and LLMs) love

Get started for freeTalk to us