LW IT Solutions logo LW IT Solutions logo LW IT Solutions
« Blog-Übersicht /Digital Analytics / Tutorial: GA4 Analytics Advisor per API abfragen...
Diesen Artikel in anderen Sprachen lesen:

Tutorial: GA4 Analytics Advisor per API abfragen und die Antwort mit runReport prüfen

Tutorial: GA4 Analytics Advisor per API abfragen und die Antwort mit runReport prüfenTutorial: GA4 Analytics Advisor per API abfragen und die Antwort mit runReport prüfen

Management Summary

Analytics Advisor ist ein Assistent in Google Analytics, der Fragen zu Website-Ergebnissen in Alltagssprache beantwortet. Das erleichtert den Zugang zu Kennzahlen, ohne jeden Bericht selbst zusammenzustellen. Der Artikel zeigt, wie ein anderes Programm solche Fragen stellen und die Antwort mit dem zugrunde liegenden Bericht vergleichen kann. Für Marketingentscheidungen zählt dabei mehr als eine plausible Formulierung: Zeitraum und Besuchergruppe müssen passen. Übereinstimmende Zahlen erklären noch nicht die Ursache einer Veränderung.

Inhalt
  1. 1. Eine begrenzte Berichtsfrage festlegen
  2. 2. Zugriff einrichten und die erste Antwort speichern
  3. 3. In der zurückgegebenen Sitzung nachfragen
  4. 4. Die Anzahl mit runReport reproduzieren
  5. 5. Einschränkungen vor der Auswertung prüfen
  6. 6. Ein prüfbares Ergebnis festhalten
  7. Fragen und Antworten
  8. Quellen

Wie viele Sitzungen kamen über die Google-Suche, bezahlte Anzeigen oder andere Kanäle? Diese Anleitung stellt die Frage zuerst dem KI-Assistenten Analytics Advisor und vergleicht anschließend zwei Wochen. Eine zusätzliche Abfrage mit runReport prüft die genannten Zahlen direkt im GA4-Bericht. Alle Fragen und Antworten bleiben als Dateien erhalten.

Dokumentation geprüft: 25. Oktober 2026. Google bezeichnet den Assistenten in der aktuellen Anleitung als Ask Advisor. Der API-Zugriff erfolgt über properties.chat in Version v1alpha. Für die gewünschte GA4-Property müssen Zugriff und Berechtigungen vorhanden sein. [1] Ein gespeichertes Prüfprotokoll vom 27. September 2026 dokumentiert drei echte Abfragen: Für den 1.–7. September stimmten die vier Kanalgruppen aus der Chat-Tabelle mit runReport überein. Das ist ein einzelner damaliger Test, keine Zusage für spätere Antworten; vertrauliche Messwerte bleiben unveröffentlicht.

1. Eine begrenzte Berichtsfrage festlegen

Das Beispiel vergleicht den 1.–7. September 2026 mit dem 25.–31. August 2026. Beide Wochen beginnen am Dienstag und enden am Montag. Anfangs- und Endtag zählen mit. Maßgeblich ist die Berichtszeitzone der GA4-Property. sessions bezeichnet die Zahl der Sitzungen. sessionDefaultChannelGroup teilt diese Zahl nach den Standardkanälen der Sitzungen auf. Die API erwartet genau diese Feldnamen. [4] [7]

Ein Kanal fasst Zugriffsquellen zusammen, etwa unbezahlte Suchergebnisse unter „Organic Search“. Sitzungen sind Besuche im Sinne der GA4-Sitzungsregeln, keine Anzahl verschiedener Menschen. Weniger Sitzungen belegen einen Rückgang in diesem Bericht. Ob eine neue Landingpage oder eine Werbemaßnahme den Rückgang verursacht hat, bleibt damit offen.

2. Zugriff einrichten und die erste Antwort speichern

Die drei Codeblöcke laufen nacheinander in derselben Bash-Sitzung. Benötigt werden gcloud für die Anmeldung, curl für HTTP-Anfragen und jq zum Lesen und Erzeugen von JSON-Dateien. Ein neuer, privater Arbeitsordner verhindert, dass gleichnamige Ergebnisdateien einen früheren Versuch überschreiben. Die Platzhalter im ersten Block müssen durch die eigenen Kennungen und den Dateipfad ersetzt werden. Das Cloud-Projekt stellt den API-Zugang bereit; die numerische Property-ID wählt den GA4-Datenbestand. Im Cloud-Projekt muss die Analytics Data API aktiviert sein. Das angemeldete Konto braucht Zugriff auf die Property und serviceusage.services.use für das Projekt, dem die API-Nutzung zugeordnet wird.

OAuth-Berechtigungen legen fest, welche API-Funktionen die Anmeldung aufrufen darf. analytics.chatbot.read erlaubt die Chat-Abfrage, analytics.readonly die spätere Berichtsabfrage. Das Beispiel fordert beide an. gcloud speichert die Anmeldung lokal; eine neue Anmeldung kann bereits vorhandene Application Default Credentials ersetzen. Zugangsdaten und Zugriffstokens gehören nicht auf öffentliche Webseiten. [1][3][6]

Für die Analytics-Berechtigungen verwendet das Beispiel einen eigenen OAuth-Client vom Typ Desktop-App. Die heruntergeladene JSON-Datei wird über --client-id-file angegeben. Google beschreibt diesen Weg für Berechtigungen außerhalb des üblichen Cloud-Umfangs. [6] Vor jeder HTTP-Anfrage holt das Skript ein Zugriffstoken. Schlägt dieser Schritt fehl oder bleibt das Token leer, endet das Skript vor der Anfrage. HTTP-Fehler beenden den Ablauf ebenfalls; automatische Wiederholungen sind nicht eingebaut.

Shell
# Bash; gcloud, curl and jq required
set -euo pipefail
export PROJECT_ID='REPLACE_WITH_CLOUD_PROJECT'
export PROPERTY_ID='REPLACE_WITH_NUMERIC_PROPERTY_ID'
export OAUTH_CLIENT_FILE='REPLACE_WITH_DOWNLOADED_DESKTOP_CLIENT_JSON'
gcloud auth application-default login --client-id-file="$OAUTH_CLIENT_FILE" --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read,https://www.googleapis.com/auth/analytics.readonly"
gcloud auth application-default set-quota-project "$PROJECT_ID"

cat > question.json <<'JSON'
{
  "userQuery": "For 2026-09-01 through 2026-09-07, report sessions by sessionDefaultChannelGroup. Use these exact dates and API field names. State any limitation and do not infer causes.",
  "returnPropertyQuota": true
}
JSON
ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
[[ -n "$ACCESS_TOKEN" ]] || { echo "Empty access token" >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  --data-binary @question.json -o answer.json
jq '{sessionId, blocks, propertyQuota}' answer.json

Die Antwort kann Text und Tabellen enthalten. answer.json speichert die vollständige Antwort; jq zeigt ausgewählte Felder an. Eine fehlende Tabelle belegt keine Nullwerte. Tabellenzellen können beispielsweise Währungs- oder Prozentzeichen enthalten. Vor einem Zahlenvergleich müssen Einheit und Bedeutung der Spalte feststehen. [2]

3. In der zurückgegebenen Sitzung nachfragen

Die Chat-sessionId verbindet die nächste Frage mit dem bisherigen Gespräch. Diese Gesprächskennung hat nichts mit der Kennzahl sessions zu tun. Fehlt eine nichtleere Kennung, stoppt der nächste Block. Für weitere Fragen gilt jeweils die Kennung aus der jüngsten Antwort. Gespräche für verschiedene Properties oder Kunden dürfen nicht vermischt werden.

Shell
SESSION_ID=$(jq -er '.sessionId | strings | select(length > 0)' answer.json)
jq -n --arg sid "$SESSION_ID" '{
  sessionId: $sid,
  userQuery: "Compare those sessions by sessionDefaultChannelGroup with 2026-08-25 through 2026-08-31. Show both totals and absolute differences. Separate observations from hypotheses.",
  returnPropertyQuota: true
}' > followup.json
ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
[[ -n "$ACCESS_TOKEN" ]] || { echo "Empty access token" >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  --data-binary @followup.json -o followup-answer.json
jq '{sessionId, blocks, propertyQuota}' followup-answer.json

Die Folgefrage nennt den früheren Zeitraum ausdrücklich. „Organic Search ist zurückgegangen“ beschreibt eine Beobachtung. „Die neue Landingpage hat den Rückgang verursacht“ ist dagegen eine Vermutung, solange weitere Belege fehlen. Die gespeicherten Fragen zeigen später, was tatsächlich angefragt wurde.

4. Die Anzahl mit runReport reproduzieren

Nach den zwei Chat-Abfragen folgt die dritte Anfrage: runReport fordert dieselbe Kennzahl nach denselben Kanälen für beide Wochen an. Der Zahlenvergleich stützt sich damit auf einen ausdrücklich festgelegten Bericht. Beide Ergebnisse stammen weiterhin aus GA4; Übereinstimmung beweist weder eine vollständige Datenerfassung noch die Ursache einer Veränderung. [3]

Shell
cat > report-request.json <<'JSON'
{
  "dateRanges": [
    {"startDate":"2026-09-01","endDate":"2026-09-07","name":"current"},
    {"startDate":"2026-08-25","endDate":"2026-08-31","name":"previous"}
  ],
  "dimensions": [{"name":"sessionDefaultChannelGroup"}],
  "metrics": [{"name":"sessions"}],
  "limit": "1000",
  "returnPropertyQuota": true
}
JSON
ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
[[ -n "$ACCESS_TOKEN" ]] || { echo "Empty access token" >&2; exit 1; }
curl --fail-with-body --silent --show-error \
  "https://analyticsdata.googleapis.com/v1beta/properties/${PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-goog-user-project: ${PROJECT_ID}" \
  -H "Content-Type: application/json" \
  --data-binary @report-request.json -o report-response.json
jq '{dimensionHeaders,metricHeaders,rows,rowCount,metadata,propertyQuota}' report-response.json

Die Spaltennamen stehen in dimensionHeaders und metricHeaders; die Zeilenwerte folgen dieser Reihenfolge. Die zusätzliche Spalte dateRange enthält hier current oder previous. Für den Vergleich zählt daher die Kombination aus Kanal und Zeitraum, nicht die Position einer Zeile. Beispiel: 100 statt 80 Sitzungen ergeben 20 zusätzliche Sitzungen und 25 Prozent Zuwachs. Bei einem vorherigen Wert von null ist diese Prozentrechnung nicht definiert. Eine fehlende Zeile darf ohne weitere Prüfung nicht als gemessene Null behandelt werden.

Vier nummerierte Schritte: erste Frage an properties.chat in v1alpha, gespeichert als answer.json, Folgefrage mit derselben Chat-sessionId, runReport mit gleicher Kennzahl, gleichen Kanälen und Wochen, abgeglichen je Kanal und dateRange, danach Prüfung von Schwellen, Stichproben und rowCount.
runReport fragt dieselbe Kennzahl erneut ab und macht so jede Kanalzahl aus dem Chat nachprüfbar.
Zwei gleiche Waagen wiegen dasselbe Brot und kommen zum selben Ergebnis. So fragt runReport dieselbe Kennzahl für dieselben Kanäle und Wochen noch einmal fest ab und macht die Zahl aus dem Chat nachprüfbar.
Zwei gleiche Waagen wiegen dasselbe Brot und kommen zum selben Ergebnis. So fragt runReport dieselbe Kennzahl für dieselben Kanäle und Wochen noch einmal fest ab und macht die Zahl aus dem Chat nachprüfbar.

5. Einschränkungen vor der Auswertung prüfen

Der GA4-API-Antwortprüfer ist ein ergänzendes Werkzeug für gespeicherte Berichtsantworten. Der Abgleich der Chat-Zahlen bleibt ein eigener Schritt. In report-response.json sind außerdem die Angaben unter metadata zu prüfen: Schwellen können kleine Gruppen ausblenden, Stichproben können die Berechnung auf einen Teil der Ereignisse begrenzen. Übersteigt rowCount die Zahl gelieferter Zeilen, fehlen weitere Ergebnisse. Das Beispiel ruft höchstens 1.000 Zeilen ab und lädt weitere Seiten nicht automatisch nach. [8]

returnPropertyQuota fordert Informationen zum verfügbaren Kontingent an, also zu den Nutzungsgrenzen der API. Der Wert reserviert keine weiteren Aufrufe. Fehlen die Angaben, bleibt das verfügbare Kontingent unbekannt. Vor einer Wiederholung ist zu klären, ob Anmeldung, Berechtigung oder eine Nutzungsgrenze den Fehler verursacht hat. Neue Chat-Aufrufe können weiteres Kontingent verbrauchen und andere Antworten liefern. [1]

6. Ein prüfbares Ergebnis festhalten

Zum Prüfprotokoll gehören die zwei Fragen, zwei Chat-Antworten, die Berichtsanfrage, die Berichtsantwort und der Abrufzeitpunkt. Nur berechtigte Personen sollten Zugriff auf diese Dateien erhalten. Googles Datenschutzhinweis nennt die mögliche Bearbeitung von Gesprächen durch menschliche Prüfer zur Produktverbesserung. Kundennamen und vertrauliche Kampagnenpläne sind für die beschriebene Zahlenfrage nicht nötig. [5]

Das Ergebnis hält je Kanal fest, ob die Chat-Zahl mit dem Bericht übereinstimmt. Bei einer Abweichung bleiben beide Werte und die offenen Fragen dokumentiert. Auch „nicht nachvollziehbar“ ist ein brauchbares Prüfergebnis. Eine Empfehlung zum Werbebudget lässt sich aus dem bloßen Wochenvergleich nicht ableiten.

Fragen und Antworten

Warum braucht die Anmeldung einen eigenen OAuth-Client vom Typ Desktop-App?

Die beiden Analytics-Berechtigungen analytics.chatbot.read und analytics.readonly gehören nicht zum üblichen Cloud-Umfang, den gcloud mit seinem eingebauten Client anfordert. Für solche Berechtigungen beschreibt Google den Weg über einen eigenen Client, dessen JSON-Datei per --client-id-file übergeben wird. Fehlt eine der beiden Berechtigungen im Zugriffstoken, lehnt die API den jeweiligen Aufruf ab.

Die Chat-Antwort nennt für einen Kanal eine andere Zahl als runReport. Woran kann das liegen?

Bevor die Abweichung dem Assistenten zugeschrieben wird, lohnt der Abgleich der Randbedingungen. Häufige Ursachen:

  1. Zeitraum und Zeitzone. runReport rechnet mit den festgelegten Daten in der Berichtszeitzone der Property. Ob die Chat-Antwort genau dieselben Tage verwendet hat, zeigt nur ihr eigener Text oder ihre Tabelle.
  2. Kennzahl und Einteilung. Eine Spalte kann eine andere Kennzahl oder eine andere Kanaleinteilung enthalten als sessions nach sessionDefaultChannelGroup. Einheit und Bedeutung jeder Spalte müssen deshalb feststehen.
  3. Schwellen und Stichproben. Die Angaben unter metadata in report-response.json zeigen, ob kleine Gruppen ausgeblendet wurden oder nur ein Teil der Ereignisse in die Berechnung einging. Die Chat-Antwort ist gesondert auf entsprechende Hinweise zu prüfen.
  4. Fehlende Zeilen. Fehlt ein Kanal in einer der beiden Antworten, ist das keine gemessene Null.
  5. Abrufzeitpunkt. Liegen Chat und Bericht zeitlich auseinander und betrifft der Zeitraum sehr junge Tage, können sich die Daten in GA4 zwischen den Abrufen durch die laufende Verarbeitung noch ändern.

Lässt sich keine dieser Ursachen belegen, bleiben beide Werte im Protokoll stehen. Auch „nicht nachvollziehbar“ ist ein gültiges Ergebnis; ein einzelner Fall sagt nichts über die Zuverlässigkeit späterer Antworten.

Lässt sich derselbe Ablauf nacheinander für mehrere Properties verschiedener Kunden nutzen?

Ja, mit getrennten Ordnern und getrennten Gesprächen. Gespräche für verschiedene Properties dürfen nicht vermischt werden; für jede Property beginnt deshalb ein eigenes Gespräch ohne sessionId. Ein eigener Arbeitsordner je Property und Lauf verhindert außerdem, dass answer.json oder report-response.json einen früheren Stand überschreiben.

Zwei Punkte betreffen den Betrieb. Das angemeldete Konto braucht Zugriff auf jede einzelne Property, und jeder neue Chat-Aufruf kann weiteres Kontingent verbrauchen; die Angaben aus returnPropertyQuota gelten jeweils für die abgefragte Property. Und weil Googles Datenschutzhinweis die mögliche Bearbeitung von Gesprächen durch menschliche Prüfer nennt, gehören Kundennamen und vertrauliche Pläne nicht in die Fragen und die gespeicherten Dateien nur in die Hände berechtigter Personen.

Lukas Wojcik

Lukas Wojcik

Systems architect and technology enthusiast specializing in scalable tracking solutions, GMP Stack (GA4 & GTM), and robust backend architectures. Advocate for clean code and privacy-first design.

Kontakt

Eine Frage oder eine Idee für ein Webprojekt? Schreib mir kurz, worum es geht. Das Formular nutzt reCAPTCHA und formconfirmed zum Schutz vor Spam.

Kommentar schreiben

Abweichende Zahlen aus anderen Konten und Rückfragen zur Einrichtung sind hier willkommen.

Die E-Mail-Adresse wird nicht veröffentlicht. Pflichtfelder sind mit einem Stern versehen.

LUKASWOJCIK.COM · NEWSLETTER

Neue Ideen im Postfach

Neue Blogartikel, praktische Tools und Einblicke in die Projekte.

Themen auswählen (optional)
Ohne Auswahl: alle Themen.

Erst nach Bestätigung per E-Mail. · Datenschutz

Datenschutz · Newsletter

E-Mail-Adresse, Sprache, Themenauswahl sowie Anmelde- und Bestätigungszeit werden für den Newsletter gespeichert. Versand nur nach Double-Opt-in. Jede Ausgabe enthält eine sofortige Abmeldung. Formconfirmed prüft die Anmeldung auf Spam; dafür werden Formularsignale und die E-Mail-Adresse verarbeitet. Keine Öffnungs- oder Klicktracking-Pixel im Newsletter.

Vollständige Datenschutzerklärung öffnen ↗