Wie frage ich meine Analytics programmatisch ab (Stats API)?

Die Stats API ist eine öffentliche, ratenbegrenzte Abfrageschnittstelle, mit der Sie Ihre Zenovay-Analytics über HTTP abrufen können. Nutzen Sie sie, um benutzerdefinierte Dashboards zu erstellen, Live-Metriken in BI-Tools einzubetten oder Skripte von Plausible zu migrieren.

Was Sie abfragen können

Endpunkt	Was er zurückgibt
GET /stats/aggregate	Gesamtwerte über einen Zeitraum (Besucher, Seitenaufrufe, Absprungrate, durchschnittliche Sitzungsdauer).
GET /stats/timeseries	Ein Datenpunkt pro Tag, Stunde oder Monat über den Zeitraum.
GET /stats/breakdown	Top-Seiten, Top-Länder, Top-Browser — jede einzelne Dimension, nach Besuchern sortiert.

Vollständige Referenz, Parametertabellen und Beispiele: docs.zenovay.com/api/external-api (suchen Sie nach dem Abschnitt „Stats API").

Die Live-OpenAPI-3.1-Spezifikation ist unter /api/external/v1/openapi.json verfügbar — importieren Sie sie in Postman, Insomnia oder nutzen Sie sie mit einem Code-Generator.

Tarifanforderung

Die Stats API ist für Pro-, Scale- und Enterprise-Tarife verfügbar. Der Free-Tarif kann keine API-Schlüssel erstellen oder verwenden — Aufrufe geben einen 403 API_PAID_PLAN_REQUIRED-Fehler zurück. Upgrade unter Einstellungen → Abrechnung.

Ratenlimits pro Tarif

Tarif	Ratenlimit (pro Minute, Zielwert)	Monatliches Anfragekontingent
Free	10	1.000
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Wenn Sie das Ratenlimit Ihres Tarifs überschreiten, gibt die API 429 Too Many Requests mit einem Retry-After-Header zurück, der angibt, wie viele Sekunden Sie warten müssen.

Wie die Ratenbegrenzung durchgesetzt wird. Das Pro-Minuten-Limit ist ein Zielwert, keine harte Obergrenze. Wir verwenden Cloudflare's Edge-Ratenlimit, das pro Rechenzentrum mit einem kleinen Burst-Spielraum gilt — ein anhaltender Client kann daher vorübergehend das 1,5- bis 3-fache des angegebenen Werts sehen, bevor er gedrosselt wird, insbesondere wenn Anfragen über Regionen hinweg verteilt werden. Die harte Obergrenze ist das monatliche Anfragekontingent, das atomar für Ihr Konto durchgesetzt wird, unabhängig davon, woher die Anfragen stammen. Planen Sie kapazitätssensitive Workloads gegen das monatliche Kontingent; betrachten Sie den Pro-Minuten-Wert als Glättungsziel.

Schnellstart

1. API-Schlüssel erhalten (Pro+) — siehe Wie erhalte ich einen API-Schlüssel?. Schlüssel beginnen mit zv_.
2. Site-UUID finden — öffnen Sie die Website in Ihrem Zenovay-Dashboard. Die UUID befindet sich in der URL: app.zenovay.com/domains/<UUID>.
3. Ersten Aufruf durchführen:

curl -G "https://api.zenovay.com/api/external/v1/stats/aggregate" \
  -H "X-API-Key: zv_YOUR_KEY" \
  --data-urlencode "site_id=YOUR_SITE_UUID" \
  --data-urlencode "period=7d" \
  --data-urlencode "metrics=visitors,pageviews"

Sie erhalten eine Antwort in etwa dieser Form:

{
  "success": true,
  "data": {
    "results": {
      "visitors":  { "value": 12453 },
      "pageviews": { "value": 38219 }
    },
    "meta": { "period": "7d", "period_start": "...", "period_end": "..." }
  }
}

Häufige Anwendungsfälle

• Benutzerdefinierte Dashboards — aggregierte Metriken stündlich in Notion, Coda, Retool oder ein internes BI-Tool ziehen.
• Plausible-Migration — der Parameterstil (site_id, period, date, metrics, filters, property) ist absichtlich Plausible-kompatibel. Die meisten Migrationsskripte funktionieren nach dem Ersetzen der Basis-URL und dem Remapping von site_id von einer Domain zu Ihrer Zenovay-UUID.
• Einbettungen — Live-Besucherzahlen auf Ihrer Statusseite oder Marketing-Website anzeigen (verwenden Sie einen serverseitigen Proxy; setzen Sie Ihren API-Schlüssel nie in clientseitigem Code ein).
• Geplante Berichte — einmal täglich Aufschlüsselungsdaten abrufen und an Slack oder per E-Mail senden.

Filter

Sie können jede Abfrage mit Plausible-ähnlichen Filtern auf eine Teilmenge von Besuchern eingrenzen:

# Nur US-Besucher
--data-urlencode "filters=country==US"

# US- und Kanada-Besucher mit Chrome
--data-urlencode "filters=country==US,CA;browser==Chrome"

# Alle außer /admin-Seiten
--data-urlencode "filters=page!=/admin"

Zulässige Filter-Schlüssel: country, browser, device, os, source, utm_source, utm_medium, utm_campaign, page.

V1-Einschränkung: Wenn Sie filters angeben, wird in V1 nur die visitors-Metrik berechnet; andere Metriken geben null mit einem meta.note-Flag zurück. Vollständige Filterunterstützung für alle Metriken wird in V2 geliefert. Die ungefilterten Abfragen unterstützen heute alle Metriken.

Fehlerbehebung

Symptom	Ursache	Lösung
401 UNAUTHORIZED "Missing API key"	Kein X-API-Key- oder Authorization: Bearer-Header	Header hinzufügen. Schlüssel unter Einstellungen → Konto → Sicherheit & Zugang generieren, falls noch keiner vorhanden.
401 UNAUTHORIZED "Invalid API key"	Schlüssel wurde widerrufen, hat einen Tippfehler oder beginnt nicht mit zv_	Aus Einstellungen → Konto → Sicherheit & Zugang neu kopieren.
403 FORBIDDEN "requires a Pro plan"	Ihr Team ist im Free-Tarif	Upgrade unter Einstellungen → Abrechnung.
403 FORBIDDEN "does not have access"	Der API-Schlüssel ist auf eine einzelne Website beschränkt, aber site_id stimmt nicht überein	Vollzugriffsschlüssel erstellen oder mit der korrekten site_id aufrufen.
404 NOT_FOUND "Website not found"	Falsche site_id-UUID	In der Dashboard-URL überprüfen.
400 MISSING_*	Erforderlicher Abfrageparameter fehlt	site_id, period und metrics hinzufügen (immer erforderlich).
400 INVALID_METRIC	Unbekannter Metrikname	visitors, pageviews, visit_duration, bounce_rate oder events verwenden.
400 INTERVAL_PERIOD_MISMATCH	interval=hour mit einem anderen period als day	period=day mit interval=hour verwenden oder interval=day für längere Zeiträume.
429 Too Many Requests	Ratenlimit des Tarifs erreicht	Den Retry-After-Header beachten. Tarif upgraden, wenn dies regelmäßig vorkommt.

Migration von Plausible

Der Parameterstil ist absichtlich nah an Plausible's Stats API v1 angelehnt. Unterschiede:

Plausible	Zenovay	Hinweis
site_id=mysite.com	site_id=<UUID>	Plausible verwendet einen Domain-String; Zenovay eine UUID. Einmalig über GET /websites zuordnen.
period, date	period, date	Gleiche Zulassungsliste + custom:YYYY-MM-DD,YYYY-MM-DD.
metrics	metrics	visitors, pageviews, bounce_rate, visit_duration werden 1:1 zugeordnet.
filters (v1 String-Format)	filters	Gleiches key==value;key!=value-Format.
filters (v2 JSON-Array)	(V2 der Zenovay Stats API)	Erscheint später.

Nächste Schritte

• Vollständige Stats API-Referenz (Docs) — jeder Parameter, jeder Endpunkt, jeder Fehlercode.
• OpenAPI-3.1-Spezifikation — für Code-Generierung und API-Test-Tools.
• Authentifizierung — Bearer vs. X-API-Key-Header, Schlüsselrotation.
• API-Übersicht — alle anderen öffentlichen Zenovay-Endpunkte (Insights, Anomalien, Retention, LTV, NL-Abfrage).