Grundkonzepte

Die Regeln, die für alle Endpunkte gelten: Filter, Definitionen der Kennzahlen, Ausgabe als JSON und CSV, Caching, Fehlercodes und Versionierung.

Filter & allgemeine Parameter

  • project_id ist bei allen projektbezogenen Endpunkten erforderlich.
  • metrics oder metric: kommagetrennte Liste aus mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment
  • granularity: day|week|month (Wochen beginnen am Montag)
  • Zeitfenster: entweder range (Tage) oder from & to (ISO 8601). Wenn Sie to senden, ist from erforderlich. Standardwerte bei from/to: fehlendes from = vor 30 Tagen (Tagesbeginn); fehlendes to = jetzt (Tagesende).
  • Filter: model, collection_id (Tag-ID), prompt (Prompt-ID), country_code, language_code, competitors (kommagetrennte IDs)
  • include_project (standardmäßig true): Setzen Sie den Wert auf false, um Ihr Projekt auszuschließen (dann werden nur Wettbewerber zurückgegeben).

Definitionen der Kennzahlen

Diese Semantik entspricht 1:1 der Übersicht in der App.

  • mentions: Tagessummen von mentions_count. Für week/month berechnen wir die SUMME DES ZEITRAUMS (bei Wochen Montag bis Sonntag) und wiederholen diese Summe für jeden Tag des Zeitraums. Ist die Summe eines Zeitraums 0, behalten wir die letzte Zeitraumsumme ungleich 0 bei (Übernahme des letzten Werts).
  • citations: Anzahl auf Antwortebene; sie umfasst sichtbare Zitierungen und Verweise auf Hintergrundquellen. Jeder Akteur wird pro Antwort höchstens einmal gezählt. Es gelten dieselben Regeln für Zeitraumsummen und die Übernahme des letzten Werts wie bei mentions.
  • responses: Gesamtzahl der Prompt-Ausführungen (API-Aufrufe an LLMs). Verwendet die Anzahl der Ausführungen auf Projektebene, unabhängig vom Akteur. • day: Tagessumme. • week/month: Summe des Zeitraums (ohne Übernahme des letzten Werts; Tage mit 0 Ausführungen haben den Wert 0).
  • Erwähnungsrate mention_rate (auch als visibility akzeptiert): Prozentsatz pro Akteur; als Nenner dienen die Ausführungen auf Projektebene mit denselben Filtern (mentions_count / prompt_executions_count × 100). • day: Verhältnis pro Tag. • week/month: Verhältnis der Zeitraumsummen (Σ Erwähnungen / Σ Ausführungen), wiederholt für jeden Tag des Zeitraums. Ist der Nenner des Zeitraums 0, wird der letzte vorhandene Wert fortgeschrieben.
  • citation_rate: Prozentsatz der Antworten, die für den Akteur eine sichtbare Zitierung oder eine Zitierung im Hintergrund enthalten (citations_count / prompt_executions_count × 100). • day: Verhältnis pro Tag. • week/month: Verhältnis der Zeitraumsummen mit Übernahme des letzten Werts, wie bei visibility.
  • AI Visibility Score ai_visibility_score: positionsgewichtete Sichtbarkeitskennzahl, die berücksichtigt, wie weit vorn eine Erwähnung steht. Gewichtet wird mit dem Kehrwert der Position (Position 1 = 100 %, Position 2 = 50 %, Position 3 = 33 % usw.). Ein höherer Score bedeutet sowohl mehr Erwähnungen ALS AUCH bessere Positionen. • day: gewichteter Score des Tages geteilt durch die Ausführungen. • week/month: Verhältnis der Zeitraumsummen mit Übernahme des letzten Werts, wie bei visibility.
  • avg_position: durchschnittliche Position der sichtbaren Zitierungen. Zitierungen im Hintergrund haben keine sichtbare Position und werden nicht berücksichtigt. • day: Tagesdurchschnitt ohne leere Werte (null). • week/month: Durchschnitt innerhalb des Zeitraums (leere Werte werden ignoriert); anschließend wird der letzte bekannte Wert auf Tage ohne Daten fortgeschrieben, entsprechend der Glättung im Diagramm der Übersicht.
  • avg_mention_position: durchschnittliche Position der Marke, wenn sie in KI-Antworten erwähnt wird (Position 1 = zuerst erwähnt, Position 2 = an zweiter Stelle usw.). Ein kleinerer Wert ist besser. • day: Tagesdurchschnitt ohne leere Werte (null). • week/month: Durchschnitt innerhalb des Zeitraums mit Übernahme des letzten Werts.
  • Sentiment-Kennzahlen sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative: für jeden Akteur und Tag der prozentuale Anteil der Sentiment-Datensätze in der jeweiligen Kategorie an allen Sentiment-Datensätzen des Akteurs. • day: Verhältnis pro Tag (bucket_count / total_sentiments * 100). Für Tage ohne Sentiment-Datensätze wird null zurückgegeben. • week/month: Wir berechnen das Verhältnis der Zeitraumsummen (Σ bucket / Σ total * 100) und wiederholen diesen Prozentsatz für jeden Tag des Zeitraums. Ist der Nenner des Zeitraums 0, schreiben wir den letzten vorhandenen Wert fort (Übernahme des letzten Werts), entsprechend der Glättung in der Übersicht.
  • Netto-Sentiment-Score net_sentiment: Für jeden Akteur und Tag liegt der Score zwischen -100 und 100 und wird berechnet als ((very_positive + positive) − (negative + very_negative)) / total_sentiments × 100; dabei ist total_sentiments die Gesamtzahl der Datensätze in allen fünf Sentiment-Kategorien. Die Berechnung verwendet direkt die Anzahlen, ohne zuvor die Prozentwerte der einzelnen Kategorien zu runden, und rundet den resultierenden Score auf zwei Dezimalstellen. • day: berechnet den Score aus den Anzahlen dieses Tages und gibt null zurück, wenn keine Sentiment-Datensätze klassifiziert sind. • week/month: berechnet einen Score pro Zeitraum aus den über diesen Zeitraum summierten Anzahlen; die API gibt einen Punkt pro Zeitraum zurück. Enthält ein Zeitraum keine klassifizierten Sentiment-Datensätze, schreibt die API den letzten vorhandenen Score fort. In der REST-API haben leere Zeiträume am Anfang der Reihe den Wert 0. • /metrics/summary: liefert den Durchschnitt aller Punkte der Zeitreihe von net_sentiment, die einen Wert haben.

In /metrics/summary ist total bei Zählkennzahlen eine Summe und bei avg_position, avg_mention_position und net_sentiment ein Durchschnitt.

Ausgabeformate für BI-Tools

Lesende Endpunkte geben standardmäßig verschachteltes JSON zurück. Das ist im Code praktisch, für Business-Intelligence-Tools aber nicht lesbar. Mit dem optionalen Parameter output erhalten Sie dieselben Daten als rechteckige Tabelle, die Tableau, Excel, Google Sheets oder ein Data-Warehouse-Loader direkt verarbeiten können.

  • output nicht angegeben (Standard): das für jeden Endpunkt dokumentierte verschachtelte JSON. Es bleibt unverändert, bestehende Integrationen sind also nicht betroffen.
  • output=flat: dieselben Metadaten sowie columns (Spaltennamen in fester Reihenfolge), rows (ein flaches Objekt pro Zeile) und row_count.
  • output=csv: dieselben Zeilen als text/csv, mit columns als Kopfzeile.

Unterstützt von /metrics/timeseries, /metrics/summary, /metrics/sov, /metrics/prompt_summary, /metrics/top_sources, den Endpunkten unter /search_console/* und den Endpunkten unter /dimensions/*, die Listen zurückgeben. Endpunkte, deren Payload keine einzelne Tabelle ist (/metrics/agent_traffic, /metrics/ai_traffic, /search_console/summary, /dimensions/models, /dimensions/locales), lehnen output ab, statt den Parameter zu ignorieren.

/metrics/sov akzeptiert außerdem view=over_time (Standard), view=current oder view=breakdown: Die Payload enthält mehrere unterschiedliche Strukturen, eine Tabelle kann aber jeweils nur eine davon abbilden.

Spalten nach Endpunkt

Endpoint Columns
/metrics/timeseries date, actor_type, actor_id, actor_name, actor_domain, metric, value
/metrics/summary actor_type, actor_id, actor_name, actor_domain, metric, aggregation, total, min, max, last
/metrics/sov date, actor_type, actor_id, actor_name, actor_domain, share
/metrics/sov?view=current actor_type, actor_id, actor_name, actor_domain, share
/metrics/sov?view=breakdown rank, actor_type, actor_id, actor_name, actor_domain, share, others
/metrics/prompt_summary, /metrics/top_sources, /search_console/timeseries|queries|pages, /dimensions/* The keys of the endpoint's own data rows

Beispiel

GET /api/v1/metrics/timeseries?project_id=1&range=30&metrics=mentions&output=csv

date,actor_type,actor_id,actor_name,actor_domain,metric,value
2025-01-01,project,1,My Brand,mybrand.com,mentions,10
2025-01-01,competitor,2,Competitor A,competitor.com,mentions,5

Hinweise:

  • Fehler werden immer als JSON zurückgegeben, nie als CSV, damit eine fehlgeschlagene Anfrage nie für Daten gehalten wird.
  • Prozentwerte bleiben auf der ursprünglichen Skala von 0 bis 100, genau wie in der JSON-Antwort.
  • Textzellen, die mit einem Gleichheitszeichen, Pluszeichen, Minuszeichen oder At-Zeichen beginnen, werden maskiert, damit Tabellenkalkulationen sie nicht als Formeln ausführen.
  • Paginierte Endpunkte geben ihre Metadaten zur Paginierung zusätzlich in den Antwort-Headern X-Total-Count, X-Page und X-Per-Page zurück, da ein CSV-Antworttext sie nicht enthalten kann.
  • Das flache Format ist auf 200.000 Zeilen begrenzt. Grenzen Sie bei mehr Zeilen den Zeitraum ein, fordern Sie weniger Kennzahlen an oder verwenden Sie granularity=week.
  • Endpunkte ohne flaches Format lehnen output mit ERR_INVALID_PARAM ab, statt den Parameter zu ignorieren.

Cache & bedingte GET-Anfragen

Die Endpunkte für Kennzahlen (timeseries, summary, sov, top_sources) unterstützen bedingte GET-Anfragen. Wir berechnen ein ETag aus der Projektversion und einem Hash Ihrer Abfrageparameter und verwenden das updated_at des Projekts als Last-Modified.

Senden Sie If-None-Match oder If-Modified-Since, um 304 Not Modified zu erhalten, wenn sich nichts geändert hat.

Fehler

Fehler haben eine einheitliche JSON-Struktur. Werten Sie für die Fehlerbehandlung das Feld code aus. Das Feld message enthält, sofern verfügbar, Details zum Fehler, andernfalls eine Standardkennung wie missing_authorization:

Code HTTP Bedeutung
ERR_MISSING_AUTH 401 Authorization-Header fehlt oder ist fehlerhaft
ERR_INVALID_API_KEY 401 Token nicht erkannt
ERR_REVOKED_API_KEY 403 Schlüssel wurde widerrufen
ERR_INSUFFICIENT_SCOPE 403 Ein Schlüssel oder OAuth-Token mit reinem Lesezugriff wurde für eine Schreibanfrage verwendet
ERR_INSUFFICIENT_PERMISSION 403 Das Konto, dem der Schlüssel zugeordnet ist, darf diese Aktion nicht ausführen (zum Beispiel bei einem Teammitglied ohne die nötige Berechtigung)
ERR_KEY_PROJECT_SCOPED 403 Ein auf einzelne Projekte beschränkter Schlüssel wurde für einen Vorgang verwendet, der das gesamte Konto betrifft
ERR_PLAN_REQUIRED 403 Der Tarif des Kontos umfasst diesen Endpunkt nicht
ERR_INTEGRATION_UNAVAILABLE 403 Diese Funktion ist für dieses Konto oder auf dieser Domain nicht verfügbar
ERR_ACCOUNT_INACTIVE 403 Das Abonnement des Kontos wurde beendet, oder das Konto ist wegen einer unbezahlten Verlängerung pausiert
ERR_SEARCH_CONSOLE_ACCESS_REVOKED 403 Google hat dem Projekt den Zugriff auf die Search Console entzogen; verbinden Sie die Property erneut
ERR_WEB_ANALYTICS_ACCESS_REVOKED 403 Der Webanalyse-Anbieter hat die gespeicherten Zugangsdaten abgelehnt; verbinden Sie ihn erneut
ERR_DRAFT_NOT_FOUND 404 Projektentwurf nicht gefunden oder von einer anderen Person erstellt
ERR_PROJECT_NOT_FOUND 404 project_id ist für dieses Konto nicht zugänglich
ERR_NOT_FOUND 404 Ressource nicht gefunden
ERR_SEARCH_CONSOLE_NOT_CONNECTED 404 Für das Projekt ist keine Property der Google Search Console verbunden
ERR_AI_TRAFFIC_NOT_CONNECTED 404 Für das Projekt ist kein Webanalyse-Anbieter für KI-Traffic verbunden
ERR_WEB_ANALYTICS_NOT_CONNECTED 404 Für das Projekt ist kein Webanalyse-Anbieter verbunden
ERR_AGENT_TRAFFIC_NOT_CONNECTED 404 Für das Projekt ist keine Datenquelle für den Traffic von KI-Agenten verbunden
ERR_STALE_CONTENT 409 Die Aufgabe im GEO Writer wurde nach der mit der Bearbeitung gesendeten result_version neu generiert; es wurde nichts gespeichert
ERR_DRAFT_STATE 422 Projektentwurf abgelaufen oder bereits abgeschlossen, oder ein früherer Schritt fehlt (die Meldung nennt den Grund)
ERR_WEB_ANALYTICS_INVALID_QUERY 422 Der Webanalyse-Anbieter hat die Abfrage abgelehnt (die Meldung enthält seinen Validierungsfehler)
ERR_INVALID_RANGE 422 Zeitraum für die Search Console, bei dem from nach to liegt
ERR_INVALID_PARAM 422 Validierung fehlgeschlagen (siehe Meldung)
ERR_LIMIT_REACHED 422 Limit für Projekte, Prompts, technische GEO-Berichte oder Empfehlungen erreicht (die Meldung nennt das betroffene Limit)
ERR_QUOTA_EXCEEDED 422 Obergrenze für Wettbewerber, Aufgaben im GEO Writer oder Webhook-Abonnements erreicht (die Meldung nennt die betroffene Obergrenze)
ERR_RATE_LIMITED 429 Anfragelimit überschritten; warten Sie die in Retry-After angegebene Anzahl Sekunden ab
ERR_GENERATION_FAILED 502 Eine KI-Generierung ist fehlgeschlagen; wiederholen Sie die Anfrage
ERR_SEARCH_CONSOLE_UPSTREAM 503 Die Google Search Console ist nicht verfügbar oder ihr Kontingent ist ausgeschöpft; warten Sie die in Retry-After angegebene Anzahl Sekunden ab
ERR_WEB_ANALYTICS_UPSTREAM 503 Der Webanalyse-Anbieter ist nicht verfügbar oder das Kontingent des Projekts für Live-Abfragen ist ausgeschöpft; warten Sie die in Retry-After angegebene Anzahl Sekunden ab

Aufbau der Fehlerantwort:

Typische Fälle mit Status 422:

  • invalid metrics: Zulässig sind nur mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment.
  • invalid granularity: Zulässig sind nur day|week|month.
  • from/to must be ISO8601 oder from is required with to.
  • range is required, wenn weder from noch to gesendet wird.
  • unknown competitor ids: ...: IDs, die im Projekt nicht gefunden wurden.

Versionierung & Anfragelimits

Aktuelle Version: v1. Bei künftigen inkompatiblen Änderungen ändert sich die Version im Pfad (z. B. /api/v2).

Anfragelimit: 300 Anfragen pro Minute und API-Schlüssel. Für höhere Kontingente kontaktieren Sie uns.

Schreibanfragen (POST, PATCH, PUT und DELETE) werden zusätzlich auf ein zweites Budget von 60 Anfragen pro Minute und API-Schlüssel angerechnet. Ausgenommen sind der MCP-Endpunkt und POST /web_analytics/query, der nur liest.

Jede Antwort auf eine Anfrage mit API-Schlüssel enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (der Unix-Zeitstempel in Sekunden, zu dem das aktuelle Minutenfenster endet) für dieses Budget pro Schlüssel. Das Budget für Schreibanfragen hat keine eigenen Header.

Eine Anfrage, die eines der beiden Budgets überschreitet, erhält HTTP 429 mit dem Fehlercode ERR_RATE_LIMITED. Der Header Retry-After gibt die Länge des Zeitfensters dieses Budgets in Sekunden an (60): Wenn Sie so lange warten, ist das Budget in jedem Fall wieder verfügbar. Wird das Budget pro Schlüssel überschritten, enthält die Antwort mit Status 429 außerdem die drei Header X-RateLimit-*.

Die Endpunkte für Kennzahlen unterstützen bedingte GET-Anfragen (ETag/Last-Modified), siehe Cache & bedingte GET-Anfragen.