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

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.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.

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]

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.

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.