Vollständige Referenz für alle Zenovay REST API Endpunkte. Für den Einstieg siehe API Übersicht.
Eine maschinenlesbaren OpenAPI-Spezifikation ist verfügbar unter https://api.zenovay.com/api/external/v1/openapi.json, falls Sie lieber einen Client generieren möchten.
Externe API
Die Externe API verwendet API-Schlüssel-Authentifizierung und ist ein kostenpflichtiges Feature - verfügbar für Pro-, Scale- und Enterprise-Tarife. Free-Tier-Schlüssel werden mit 403 API_PAID_PLAN_REQUIRED abgelehnt.
Basis-URL
https://api.zenovay.com/api/external/v1
Authentifizierung
Generieren Sie einen Schlüssel unter Konto → Sicherheit & Zugriff (oder öffnen Sie app.zenovay.com/api-keys direkt). Schlüssel beginnen mit zv_. Fügen Sie Ihren Schlüssel in jede Anfrage ein, entweder mit dem Header:
X-API-Key: zv_YOUR_API_KEY
# oder
Authorization: Bearer zv_YOUR_API_KEY
Antwortenveloppe
Jede Antwort der Externen API ist in eine Standard-Veloppe verpackt. Erfolgreiche Antworten sehen so aus:
{
"success": true,
"data": { },
"timestamp": "2026-06-13T00:00:00.000Z"
}
Die folgenden Beispiele zeigen den Inhalt des data Objekts. Fehler verwenden ein separates Format - siehe Fehlerantworten.
Analytics-Endpunkte
Analytics-Übersicht abrufen
GET /analytics/{websiteId}
Gibt eine aggregierte Analytics-Zusammenfassung für eine Website zurück.
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
| range | string | Zeitraum: 24h, 7d, 30d, 90d, 1y (Standard: 7d) |
data:
{
"website": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website"
},
"time_range": "7d",
"date_range": {
"start": "2026-06-06",
"end": "2026-06-13"
},
"summary": {
"total_visitors": 1247,
"total_page_views": 3891,
"unique_visitors": 982
},
"daily_stats": []
}
daily_stats enthält die rohen analytics_daily Reihen für den Bereich. Für eine Plausible-ähnliche Abfrage-API (visitors, pageviews, bounce_rate, visit_duration mit Filtern und Breakdowns) siehe die Stats API.
Besucher abrufen
GET /analytics/{websiteId}/visitors
Gibt einzelne Besucherdatensätze für eine Website zurück.
Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
| range | string | Zeitraum (Standard: 7d) |
| limit | integer | Ergebnisse pro Seite (Standard: 100, max: 1000) |
| offset | integer | Anzahl der zu übersprungenen Datensätze (Standard: 0) |
Seiten abrufen
GET /analytics/{websiteId}/pages
Gibt die Top-Seiten für eine Website zurück. Akzeptiert range und limit (Standard 20, max 100).
Länder abrufen
GET /analytics/{websiteId}/countries
Gibt eine geografische Aufschlüsselung der Besucher nach Land zurück. Akzeptiert range und limit (Standard 20, max 100).
Technologie abrufen
GET /analytics/{websiteId}/technology
Gibt die Technologie-Aufschlüsselung zurück - devices, browsers und operating_systems, jeweils mit Counts und Prozentsätzen. Akzeptiert range.
Website-Endpunkte
Websites auflisten
GET /websites
Gibt alle Websites zurück, auf die Ihr API-Schlüssel Zugriff hat.
data:
{
"websites": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website",
"tracking_code": "abc123def456",
"is_active": true,
"created_at": "2026-01-01T00:00:00Z"
}
],
"total": 1
}
Website-Details abrufen
GET /websites/{websiteId}
Gibt Details für eine bestimmte Website unter data.website zurück.
Heatmap-Endpunkte
Heatmap-Seiten abrufen
GET /heatmaps/{websiteId}/pages
Gibt Seiten zurück, für die Heatmap-Daten erfasst wurden. Akzeptiert limit (Standard 20, max 100).
Sitzungsaufzeichnungs-Endpunkte
Aufzeichnungssitzungen abrufen
GET /replays/{websiteId}/sessions
Gibt Session-Replay-Aufnahmen für eine Website zurück. Akzeptiert limit (Standard 50, max 200) und offset.
Fehlerverfolgung-Endpunkte
Fehlergruppen abrufen
GET /errors/{websiteId}/groups
Gibt gruppierte Fehlerdaten für eine Website zurück. Akzeptiert limit (Standard 50, max 200) und einen optionalen status Filter (open, resolved, ignored).
KI & Erweiterte Endpunkte (Pro+)
Diese Endpunkte erfordern einen Pro-Plan oder höher und gelten basierend auf dem Plan des besitzenden Websites-Teams.
| Endpunkt | Beschreibung |
|---|---|
GET /insights/{websiteId} | Von KI generierte Insights für die Website |
GET /anomalies/{websiteId} | Erkannte Traffic-/Verhaltens-Anomalien |
GET /retention/{websiteId} | Kohortenanalyse (Retention) (granularity, periods) |
GET /revenue/{websiteId}/ltv | Lifetime-Value Kohortenanalyse |
Natürlichsprachige Abfrage (Scale+)
POST /query/{websiteId}
Führt eine natürlichsprachige Analytics-Abfrage aus. Erfordert einen Scale-Plan oder höher. Senden Sie einen JSON-Body mit einer query-Zeichenkette (max 500 Zeichen); jeder Aufruf verbraucht 3 Query-Credits.
Stats API
Plausible-kompatible schreibgeschützte Abfrage-Endpunkte (Pro+). Diese ermöglichen es Ihnen, Metriken, Zeitreihen und Breakdowns mit Filtern abzufragen. Siehe das dedizierte Stats API Handbuch für die vollständige Parameterreferenz.
| Endpunkt | Beschreibung |
|---|---|
GET /stats/aggregate | Einzelne Metriken über einen Zeitraum |
GET /stats/timeseries | Zeitstempel-gebundene Reihen (interval=day/hour/month) |
GET /stats/breakdown | Group-by Metriken (Top-Seiten, Top-Länder usw.) |
Alle drei benötigen site_id plus period, metrics und optionale filters. Unterstützte Metriken sind visitors, pageviews, bounce_rate, visit_duration und events.
Nutzungs-Endpunkt
API-Nutzung prüfen
GET /usage
Gibt Ihre aktuelle API-Nutzung und Limits zurück.
data:
{
"api_key": {
"id": "key_123",
"name": "Personal API key",
"permission": "full_access",
"website_id": null,
"auth_kind": "user"
},
"usage": {
"monthly_requests": 4521,
"monthly_limit": 10000,
"monthly_remaining": 5479,
"monthly_reset_at": "2026-07-01T00:00:00.000Z",
"total_requests": 18204,
"scope": "user"
},
"rate_limits": {
"requests_per_minute": 30
},
"subscription": {
"tier": "Pro"
}
}
Tracking-Endpunkte (öffentlich)
Diese Endpunkte erfordern keine API-Schlüssel-Authentifizierung. Sie verwenden den Website-Tracking-Code und sind auf jedem Plan offen (nur Rate-Limited).
Seitenaufruf oder Ereignis tracken
POST /e/{trackingCode}
Sendet einen Seitenaufruf oder ein benutzerdefiniertes Ereignis. Dies wird automatisch vom Tracking-Skript verwendet. Für serverseitiges Tracking senden Sie dasselbe Payload-Format mit den entsprechenden Headern. Heartbeat-Ereignisse können auch als heartbeat Ereignistyp zu diesem Endpunkt gesendet werden.
Live-Besucheranzahl
GET /e/live/{trackingCode}
Gibt die aktuelle Anzahl der Live-Besucher auf der Website mit einer kurzen Liste aktiver Sitzungen zurück.
Heartbeat
POST /e/heartbeat/{trackingCode}
Sendet ein Heartbeat-Signal um eine Besuchersitzung aktiv zu halten. Erfordert eine session_id im JSON-Body.
Fehlerantworten
Fehlerformat
Fehler werden mit success: false und einem error Objekt zurückgegeben:
{
"success": false,
"error": {
"message": "site_id parameter is required",
"code": "MISSING_SITE_ID",
"timestamp": "2026-06-13T00:00:00.000Z"
}
}
Häufige Fehlercodes
| Code | HTTP-Status | Beschreibung |
|---|---|---|
| UNAUTHORIZED | 401 | API-Schlüssel ungültig oder fehlt |
| API_PAID_PLAN_REQUIRED | 403 | API-Zugriff erfordert einen Pro-Plan oder höher |
| FORBIDDEN | 403 | Schlüssel hat keinen Zugriff auf die angeforderte Website oder Plan-Tier zu niedrig |
| NOT_FOUND | 404 | Ressource nicht gefunden |
| VALIDATION_ERROR | 400 | Ungültiger oder fehlender Parameter |
| MISSING_SITE_ID | 400 | site_id Query-Parameter erforderlich (Stats API) |
| RATE_LIMIT_EXCEEDED | 429 | Pro-Minute Rate-Limit überschritten |
| MONTHLY_LIMIT_EXCEEDED | 429 | Monatliches API-Anfragelimit erreicht |
| INTERNAL_ERROR | 500 | Interner Fehler |
Rate Limits
Externe API Rate Limits gelten pro API-Schlüssel. (Die Free-Zeile wird der Vollständigkeit halber angezeigt, aber Free-Tier-Schlüssel können die Externe API nicht aufrufen - es ist ein kostenpflichtiges Feature.)
| Plan | Anfragen/Minute | Monatliches Limit |
|---|---|---|
| Pro | 30 | 10.000 |
| Scale | 60 | 100.000 |
| Enterprise | 120 | 1.000.000 |
Antworten enthalten Nutzungs- und Rate-Limit-Header:
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z
Wenn ein Pro-Minute-Limit erreicht wird, enthält die Antwort auch einen Retry-After Header (Sekunden zum Warten).