GET /api/audits/:id/google - MetricSpot Docs

Was dieser Endpunkt macht

GET /api/audits/:id/google liefert den Organic-Traffic-Snapshot eines Audits, gezogen aus der vom Nutzer verknüpften Google Analytics 4-Property und Google Search Console-Site.

Liefert { "connected": false }, wenn der Nutzer Google noch nicht verknüpft hat.
Liefert { "connected": true, "linked": false }, wenn Google verbunden ist, die URL des Audits aber keiner GA4-Property und keinem GSC-Site zugeordnet ist.
Bei Verbunden + verknüpft: voller Snapshot: GA4-Traffic, GSC-Queries und Indexing-Extras.
24 Stunden serverseitig gecached pro (user_id, url), sodass Wiederholungen am selben Tag günstig und idempotent sind.
Pro-only und an Google-OAuth-Scope gebunden: liefert 403, wenn dem Token Google-Zugriff fehlt oder der Plan die Integration nicht umfasst.

Warum das wichtig ist

Audits ohne Traffic-Daten sagen Agenten, was zu beheben ist, aber nicht, was zuerst. Der Organic-Traffic-Snapshot erlaubt einem Agenten, fehlerhafte Seiten nach echtem organischen Wert zu sortieren, sodass die Empfehlungen auf URLs landen, die wirklich Umsatz bringen.

Konkrete Workflows:

Ein “Wo fange ich an?”-Agent ruft GET /api/audits/:id für Findings und GET /api/audits/:id/google für Sessions auf und entwirft eine Fix-Liste sortiert nach Sessions 28d pro Landingpage.
Ein Query-Gap-Agent liest gsc.top_queries (hohe Impressionen, niedrige CTR) und schreibt Titel und Meta-Description der betroffenen Seite um, um CTR zu heben.

Wie du ihn nutzt

Der Nutzer muss zuerst Google Analytics 4 und Search Console im MetricSpot-Dashboard verbinden, dann jede Audit-URL explizit einer GA4-Property und einer GSC-Site zuordnen. Ohne Zuordnung läuft der Endpunkt weiter mit linked: false, damit Agenten elegant degradieren können.

Request

GET /api/audits/12345/google HTTP/1.1
Host: app.metricspot.com
Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx

curl

curl https://app.metricspot.com/api/audits/12345/google \
  -H "authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Node fetch

const res = await fetch("https://app.metricspot.com/api/audits/12345/google", {
  headers: { authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx" },
});
const data = await res.json();

if (!data.connected) {
  console.log("Google verknüpfen auf app.metricspot.com/settings/integrations");
} else if (!data.linked) {
  console.log("Diese URL einer GA4-Property und einer GSC-Site zuordnen");
} else {
  console.log(`Sessions 28d: ${data.ga4?.sessions_28d}`);
  for (const q of data.gsc?.top_queries?.slice(0, 5) ?? []) {
    const ctr = q.impressions ? q.clicks / q.impressions : 0;
    console.log(`${q.query}: CTR ${(ctr * 100).toFixed(1)}%`);
  }
}

Python httpx

import httpx

r = httpx.get(
    "https://app.metricspot.com/api/audits/12345/google",
    headers={"authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"},
    timeout=30.0,
)
data = r.json()
if not data.get("connected"):
    print("Google verknüpfen auf app.metricspot.com/settings/integrations")
elif not data.get("linked"):
    print("Diese URL einer GA4-Property und einer GSC-Site zuordnen")
else:
    print("Sessions 28d:", (data.get("ga4") or {}).get("sessions_28d"))

Antwort

Verbunden und zugeordnet

200 OK:

{
  "connected": true,
  "linked": true,
  "ga4": {
    "sessions_28d": 14328,
    "sessions_trend": [
      { "date": "2026-04-16", "sessions": 482 },
      { "date": "2026-04-17", "sessions": 511 }
    ],
    "top_landing_pages": [
      { "url": "https://example.com/", "sessions": 5104 },
      { "url": "https://example.com/pricing", "sessions": 2871 }
    ]
  },
  "gsc": {
    "top_queries": [
      { "query": "example pricing", "clicks": 612, "impressions": 8412, "position": 4.2 },
      { "query": "example alternative", "clicks": 387, "impressions": 5101, "position": 7.8 }
    ],
    "indexing": {
      "indexed_pages": 184,
      "coverage_issues": 3
    }
  },
  "ga_property_used": {
    "property_id": "properties/123456789",
    "display_name": "Example - GA4"
  },
  "gsc_site_used": {
    "site_url": "https://example.com/"
  }
}

Felder:

connected: true, wenn das Konto einen aktiven Google-OAuth-Grant hat. false, dann werden die anderen Felder weggelassen.
linked: true, wenn die URL dieses Audits einer GA4-Property oder einem GSC-Site zugeordnet ist. false heißt, der Nutzer muss im Dashboard zuordnen.
ga4.sessions_28d: Gesamte organische Sessions in den letzten 28 Tagen.
ga4.sessions_trend: Tagesreihe der organischen Sessions, älteste zuerst.
ga4.top_landing_pages: Array { url, sessions }, sortiert nach Sessions absteigend.
gsc.top_queries: Array { query, clicks, impressions, position }, sortiert nach Clicks absteigend.
gsc.indexing: optionales Objekt mit indexed_pages und coverage_issues aus GSC.
ga_property_used / gsc_site_used: die Zuordnung, die der Audit verwendet hat, zur Anzeige.

Verbunden, aber ohne Zuordnung

{ "connected": true, "linked": false }

Nicht verbunden

{ "connected": false }

Re-Auth erforderlich

Wenn das gespeicherte OAuth-Token nicht aktualisiert werden kann (widerrufen oder über den Refresh hinaus abgelaufen), wird die Verbindungszeile gelöscht und der Endpunkt liefert:

{ "connected": false, "reason": "reauth_required" }

Häufige Fehler

Code	Wann	Aktion
`UNAUTHORIZED` (401)	Bearer-Token fehlt oder ist ungültig	Schlüssel erzeugen auf `app.metricspot.com/settings/api-keys`
`FORBIDDEN` (403)	Plan ohne Google-Integration oder Audit fremder Kontos	Auf Pro upgraden oder Besitzerkonto nutzen
`AUDIT_NOT_FOUND` (404)	Audit-id existiert nicht	Eigenen Audit übergeben
`INVALID_URL` (400)	`:id` keine positive ganze Zahl	Ganzzahlige id übergeben
`UPSTREAM_FAILED` (5xx)	GA4- oder GSC-API-Ausfall	Erneut versuchen; Antwort wird bei Erfolg 24h gecached

Häufig gestellte Fragen

Warum `linked: false`, obwohl ich Traffic in GA4 sehe?

Die Verknüpfung liegt pro URL auf der MetricSpot-Seite. Nach dem Verbinden von Google auf app.metricspot.com/settings/integrations musst du jede Audit-URL einer konkreten GA4-Property und GSC-Site zuordnen. MetricSpot macht das, weil ein Google-Konto oft viele GA4-Properties hat; explizite Zuordnung verhindert das Greifen der falschen.

Warum ein 28-Tage-Fenster?

Es entspricht der Standardausgabe von GSC für Top-Queries und ist kurz genug, um aktuelle Änderungen (post-Deploy, post-Launch) abzubilden und lang genug, um wöchentliche Saisonalität zu glätten. Das Fenster ist in v1 nicht konfigurierbar.

Wie frisch sind die Daten?

GA4-Daten hinken typischerweise 24 bis 48 Stunden hinter Echtzeit, gemäß Googles Verarbeitungsfenster. GSC-Daten hinken 2 bis 3 Tage. Der Endpunkt cached erfolgreiche Antworten 24 Stunden pro (user_id, url), Wiederholungen am selben Tag liefern denselben Snapshot.

Verbraucht das Audit-Kontingent?

Nein. Dieser Endpunkt ist über Plan und Google-API-Quote hinaus nicht gemessen. Der 24-Stunden-Cache stellt außerdem sicher, dass eine CI-Schleife, die diesen Endpunkt hämmert, Googles Tageslimits nicht sprengt.