Tutorial: 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
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.
# 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.jsonDie 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.
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.jsonDie 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]
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.jsonDie 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.

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:
- 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.
- 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.
- 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.
- Fehlende Zeilen. Fehlt ein Kanal in einer der beiden Antworten, ist das keine gemessene Null.
- 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.


