Collect- & Lese-API

Collect-Endpunkt

Das Script und alle SDKs senden Daten an POST /api/collect (Alias /api/v1/collect). Eine Authentifizierung ist nicht nötig — die Website-ID ist die öffentliche Kennung. Web-Requests müssen von der registrierten Domain oder einer Subdomain kommen.

POST https://trackd.one/api/collect
Content-Type: application/json

{ "type": "pageview", "website_id": "YOUR_WEBSITE_ID", "url": "https://example.com/pricing" }

Kein SDK für deine Plattform? Sende Events direkt, z. B. von einem Server, einer CLI oder einer Game-Engine:

curl -X POST https://trackd.one/api/collect \
  -H "Content-Type: application/json" \
  -d '{
    "website_id": "YOUR_WEBSITE_ID",
    "context": { "platform": "server", "app_version": "1.0.0" },
    "events": [
      { "type": "screen_view", "name": "Home" },
      { "type": "event", "event_name": "signup", "event_data": { "plan": "pro" } }
    ]
  }'

Batches

Apps sollten Batches senden (max. 50 Events pro Request). Die context-Felder werden in jedes Event übernommen:

{
  "website_id": "YOUR_WEBSITE_ID",
  "context": { "platform": "android", "app_version": "2.3.1", "os_version": "Android 15" },
  "events": [
    { "type": "screen_view", "name": "Home" },
    { "type": "event", "event_name": "signup", "event_data": { "plan": "pro" } }
  ]
}

Felder

Feld	Typen	Hinweis
type	alle	pageview, event, screen_view, app_event, vitals, heatmap, ab_assign, ab_convert
website_id	alle	UUID, Pflicht (pro Event oder im Batch)
url	pageview, event	vollständige URL (Web), Pflicht für pageview
name	screen_view	Screen-Name, z. B. Home (gespeichert als Pfad /Home)
event_name	event	Pflicht, max. 200 Zeichen
event_data	event	flaches JSON-Objekt, max. 4 KB
platform, app_version, os_version	alle	z. B. android, 2.3.1, Android 15
session_id	alle	optional, flüchtig und nur im Speicher, 8–64 Zeichen; nie dauerhaft speichern
timestamp	alle	optional (ms oder ISO) für verzögert gesendete Events, max. 72 h alt

Antworten

• 202 { "ok": true, "accepted": 3, "rejected": 0 }
• 400 ungültiges JSON / kein gültiges Event, 404 unbekannte Website, 403 Domain stimmt nicht (nur Web), 413 Body größer als 64 KB
• 429 Rate-Limit oder monatliches Event-Limit erreicht (siehe Retry-After-Header)

Rate-Limits: 600 Requests/Minute pro IP, 120 Requests/Minute pro IP und Website. Aus Browsern sendest du den Body als text/plain (kein CORS-Preflight); er wird als JSON gelesen.

API-Schlüssel

Greife programmatisch auf deine Statistiken zu. Erzeuge einen Schlüssel unter Konto → API-Schlüssel (Benutzermenü unten links) (ab Pro). Der Schlüssel wird nur einmal angezeigt — kopiere ihn sofort.

Lese-API (v1)

Sende den Schlüssel als Bearer-Token. from/to sind ISO-Zeitstempel (Standard: letzte 7 Tage).

curl "https://trackd.one/api/v1/websites/YOUR_WEBSITE_ID/stats?from=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer tp_xxxxxxxx"

Methode	Pfad	Ergebnis
GET	/api/v1/websites	alle Projekte
GET	/api/v1/websites/:id/stats?from&to	Kennzahlen
GET	/api/v1/websites/:id/timeseries?from&to&interval=day|hour&tz=Europe/Berlin	Zeitreihe
GET	/api/v1/websites/:id/top/:field?from&to&limit	Top-Liste
GET	/api/v1/websites/:id/events?from&to	Events
GET	/api/v1/websites/:id/realtime	aktive Besucher und Seiten

Erlaubte Werte für :field: pathname, referrer, country, browser, os, device, language, hostname, utm_source, utm_medium, utm_campaign, platform, app_version, os_version.

Filter

Alle Auswertungs-Endpunkte akzeptieren Filter als filter_<feld>=<wert> (exakte Übereinstimmung, kombinierbar), z. B. ?filter_platform=android&filter_app_version=2.3.1.