Link-Statistik-API

GET /v1/urls/{slug}/stats gibt voraggregierte Analysen für einen Ihrer Links zurück. Eigentümer-beschränkt, cookielos, nur aggregiert (keine Zeilen pro Klick, keine Besucherkennungen — siehe Wie wir zählen). Die Web-App-Route /x/urls/{slug}/stats gibt denselben Body zurück.

Anfrage

GET /v1/urls/{slug}/stats?from=YYYY-MM-DD&to=YYYY-MM-DD
Authorization: Bearer YOUR_TOKEN_HERE

Erzeugen Sie ein Token in Ihren Kontoeinstellungen.

Parameter	Wo	Erforderlich	Standard	Hinweise
slug	Pfad	ja	—	Ein Link, der Ihnen gehört (sonst 404).
from	Query	nein	to − 29 Tage	Fensteranfang, UTC-Datum YYYY-MM-DD.
to	Query	nein	heute (UTC)	Fensterende, UTC-Datum; niemals in der Zukunft.

Fenster-Semantik (begrenzen, nicht ablehnen). from wird auf die Analyse-Aufbewahrung Ihres Plans begrenzt. Ein Fenster, das länger als Ihre Aufbewahrung ist, ist kein Fehler — es wird begrenzt und der effektive Anfang wird in range.clampedTo zurückgegeben (mit retentionDays und storedDays). Ein fehlerhaftes Fenster (from nach to oder ein nicht parsbares Datum) ist ein 400.

Ratenbegrenzung. Pro Abonnent 60 Anfragen/Minute; bei Überschreitung wird 429 mit einem Retry-After-Header zurückgegeben.

Antwort 200

{
  "stats": {
    "slug": "spring-sale",
    "zoneDomain": "snipzr.li",
    "range": { "from": "2026-06-14", "to": "2026-07-13", "clampedTo": "2026-06-14", "retentionDays": 30, "storedDays": 122 },
    "allTime": { "total": 5120, "preTracking": 4900, "trackingSince": "2026-07-13" },
    "totals": { "human": 82, "bots": 61, "requests": 143, "qr": 12, "click": 70 },
    "series": [ { "date": "2026-07-12", "n": 90, "b": 40 }, { "date": "2026-07-13", "n": 53, "b": 21 } ],
    "hourly": { "fromUtc": "2026-07-12T16:00:00Z", "buckets": [0,0,1,2,3,4,6,8,7,9,5,6,4,3,2,2,1,3,4,2,1,0,0,0] },
    "geo": [ { "k": "US", "v": 40 }, { "k": "DE", "v": 22 }, { "k": "unknown", "v": 3 } ],
    "referrers": [ { "k": "~direct", "v": 31 }, { "k": "reddit.com", "v": 18 }, { "k": "~other", "v": 4 } ],
    "devices": [ { "k": "desktop", "v": 51 }, { "k": "mobile", "v": 28 } ],
    "browsers": [ { "k": "chrome", "v": 40 } ],
    "os": [ { "k": "windows", "v": 25 } ],
    "languages": [ { "k": "en", "v": 60 } ],
    "source": { "click": 70, "qr": 12 },
    "freshness": "todayLive"
  }
}

Felder

Feld	Bedeutung
range	Effektives Fenster + Aufbewahrungs-/Begrenzungs-Metadaten (clampedTo = effektiver Anfang; storedDays kann retentionDays übersteigen).
allTime	Lebenszeit-Aufrufe, aufgeteilt in Vor-Erfassungs- vs. erfassten Zeitraum.
totals	Fenstersummen. human = requests − bots ist die Hauptzahl; requests (roh, inkl. Bots/Monitore) — nicht darauf abrechnen oder alarmieren.
series	Pro UTC-Tag {date, n, b} (Mensch = n − b), aufsteigend, Null-Tage weggelassen.
hourly	Gleitende letzte 24 Stunden menschlicher Klicks nach UTC-Stunde, unabhängig vom Fenster (leer bei einem rein historischen Fenster).
geo,referrers,devices,browsers,os,languages	[{k, v}], absteigend nach v sortiert. Verweise sind nur-Host; Sentinels ~direct (kein Verweis) und ~other (zusammengefasster Rest). Länderschlüssel unknown, wenn nicht bestimmbar.
source	{click, qr}-Aufteilung menschlicher Klicks.
freshness	todayLive | final | degraded.

Zählungen sind pro UTC-Tag monoton nicht abnehmend, außer einem kurzen Rückgang während eines stündlichen Konsolidierungsfensters — sie pendeln sich innerhalb der Stunde ein. Behandeln Sie einen vorübergehenden Rückgang am selben Tag nicht als Datenverlust.

Fehler

Status	Wann
400	fehlerhaftes Fenster (from > to, ungültiges Datum) oder ungültiger Slug
404	Slug für diesen Eigentümer nicht gefunden
429	über der Ratenbegrenzung pro Token (Retry-After-Header)
503	Analysespeicher nicht erreichbar und keine Live-Daten decken das Fenster ab

Ein degraded-200 (Speicher aus, aber aktuelle Live-Daten verfügbar) unterscheidet sich von einem 503 (nichts auslieferbar) — stellen Sie freshness: "degraded" als „nur aktuelle Daten" dar.

Beispiel

curl -H "Authorization: Bearer $SNIPZR_TOKEN" \
  "https://api.snipzr.com/v1/urls/spring-sale/stats?from=2026-06-14&to=2026-07-13"

JSON-Schema

Die Antwort wird durch ein veröffentlichtes JSON-Schema (2020-12) beschrieben: https://snipzr.com/schemas/v1/link-stats.schema.json. Richten Sie Ihren Validator oder Codegenerator auf diese URL.

Versionierung

Additive, abwärtskompatible Felder können ohne Versionssprung erscheinen — tolerieren Sie unbekannte Felder. Entfernungen/Umbenennungen sind eine neue Hauptversion. Die Web-App kann dieselben Daten als CSV exportieren (Langformat date,metric,key,value); die API ist nur JSON.