Synupv1
Schlüssel erstellen
v1Ressourcen/AEO

AEO

Verfolgen der Sichtbarkeit eines Standorts in KI-Antwortmaschinen (ChatGPT, Gemini, Perplexity): wie oft er erwähnt wird, wo er gegenüber Wettbewerbern rankt und was seinen Score bremst.

Liefert den neuesten KI-Sichtbarkeitsbericht für einen Standort: Gesamt- und Engine-Scores, die Keyword-/Prompt-Matrix, Wettbewerbslücken- und Ranking-Vergleiche, Quellenabdeckung, Stimmung und empfohlene Maßnahmen. Die Berichtsgenerierung erfolgt asynchron — dies ist zugleich das Polling-Ziel für POST /api/v1/aeo/reports/enqueue: Rufen Sie diesen Endpunkt weiter auf und beobachten Sie das Feld generating, bis es wieder auf false springt und generatedAt aktualisiert wird. Übergeben Sie prompt, um in einen einzelnen verfolgten Prompt einzutauchen, statt den vollständigen Bericht zu erhalten.

AEO-Bericht eines Standorts abrufen

get/api/v1/aeo/reports
aeo:read
Query-Parameter
locationIdstringerforderlich
Der abzurufende Standort.
clientIdstringoptional
Der Kunde des Standorts.
promptstringoptional
In einen einzelnen verfolgten Prompt eintauchen (Abgleich ohne Beachtung der Groß-/Kleinschreibung), statt den vollständigen Bericht zurückzugeben. Liefert null-Zellen, wenn der Prompt nicht in der Matrix dieses Standorts vorkommt.
Antwort
dataobjectoptional
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
404Die Ressource wurde nicht gefunden oder gehört nicht zu Ihrer Agentur.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
get/api/v1/aeo/reports
Ihr API-Schlüssel
locationId *
clientId
prompt
{
  "data": {
    "generatedAt": "2026-02-01T06:00:00.000Z",
    "generating": false,
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "visibility": {
      "overall": 62,
      "label": "GOOD",
      "message": "Your business shows up for most of the prompts you're tracking.",
      "engines": {
        "ChatGPT": {
          "score": 68,
          "comparisonPct": 12,
          "configured": true
        },
        "Gemini": {
          "score": 56,
          "comparisonPct": -4,
          "configured": true
        },
        "Perplexity": {
          "score": null,
          "comparisonPct": null,
          "configured": false
        }
      }
    },
    "metrics": {
      "visibility": {
        "value": 62,
        "delta": 5
      },
      "mentionRate": {
        "value": 71,
        "delta": 3
      },
      "avgPosition": {
        "value": 2.1,
        "delta": -0.4
      },
      "promptsCovered": {
        "value": 8,
        "total": 10
      },
      "sourcesCited": {
        "value": 14,
        "delta": 2
      }
    },
    "keywordMap": {
      "ChatGPT": [
        {
          "keyword": "best dentist austin",
          "percentage": 82,
          "dataSources": [
            {
              "name": "Google Business Profile"
            }
          ]
        }
      ],
      "Gemini": [
        {
          "keyword": "emergency dentist austin",
          "percentage": 54,
          "dataSources": []
        }
      ],
      "Perplexity": []
    },
    "matrix": [
      {
        "keyword": "best dentist austin",
        "cells": {
          "ChatGPT": {
            "score": 82,
            "mentioned": true,
            "rank": 1,
            "answerExcerpt": "Acme Dental — Downtown is highly rated for..."
          },
          "Gemini": {
            "score": 54,
            "mentioned": true,
            "rank": 3,
            "answerExcerpt": null
          },
          "Perplexity": null
        },
        "best": 82
      }
    ],
    "gap": [
      {
        "business": "Acme Dental — Downtown",
        "isYou": true,
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "comparisonPct": null
      },
      {
        "business": "Smile Bright Dental",
        "isYou": false,
        "overall": 71,
        "chatgpt": 74,
        "gemini": 68,
        "perplexity": null,
        "comparisonPct": 9
      }
    ],
    "ranking": {
      "All": {
        "primary": {
          "good": 6,
          "neutral": 2,
          "bad": 2
        },
        "competitors": []
      },
      "ChatGPT": {
        "primary": {
          "good": 7,
          "neutral": 1,
          "bad": 2
        },
        "competitors": []
      },
      "Gemini": {
        "primary": {
          "good": 5,
          "neutral": 3,
          "bad": 2
        },
        "competitors": []
      },
      "Perplexity": {
        "primary": {
          "good": 0,
          "neutral": 0,
          "bad": 0
        },
        "competitors": []
      }
    },
    "radar": {
      "ChatGPT": {
        "relevance": 78,
        "reviews": 88,
        "engagement": 65,
        "freshness": 74,
        "citations": 81
      },
      "Gemini": {
        "relevance": 70,
        "reviews": 80,
        "engagement": 75,
        "freshness": 85,
        "citations": 65
      },
      "Perplexity": {
        "relevance": 0,
        "reviews": 0,
        "engagement": 0,
        "freshness": 0,
        "citations": 0
      }
    },
    "factors": [
      {
        "key": "citations",
        "label": "Citations",
        "value": 81,
        "detail": "Cited by 14 of 20 tracked sources across configured engines.",
        "action": {
          "label": "Fix missing citations",
          "target": "citations"
        }
      }
    ],
    "citations": {
      "summary": {
        "totalSources": 20,
        "active": 14,
        "detected": 4,
        "missing": 2,
        "missingDirectories": [
          "Yelp"
        ]
      },
      "byEngine": {
        "ChatGPT": [
          {
            "name": "Google Business Profile",
            "status": "active"
          }
        ],
        "Gemini": [],
        "Perplexity": []
      }
    },
    "sentiment": {
      "positive": 62,
      "neutral": 30,
      "negative": 8,
      "mentions": []
    },
    "attention": [
      {
        "text": "Bing Places is missing your current hours.",
        "tone": "warn"
      }
    ],
    "recommendations": [
      {
        "id": "rec_reviews_1",
        "kind": "opportunity",
        "priority": "high",
        "title": "Add more customer reviews mentioning services",
        "detail": "Reviews that name specific services improve how often engines cite you for those prompts.",
        "action": {
          "label": "Request reviews",
          "target": "reviews"
        }
      }
    ],
    "history": [
      {
        "yearMonth": "2026-01",
        "overall": 57,
        "chatgpt": 61,
        "gemini": 53,
        "perplexity": null,
        "sources": 12
      },
      {
        "yearMonth": "2026-02",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "sources": 14
      }
    ],
    "competitorHistory": [
      {
        "name": "Smile Bright Dental",
        "points": [
          {
            "yearMonth": "2026-01",
            "overall": 65
          },
          {
            "yearMonth": "2026-02",
            "overall": 71
          }
        ]
      }
    ]
  }
}
v1Ressourcen/AEO/postAEO-Berichtsgenerierung einreihen

Startet eine Hintergrundgenerierung eines neuen AEO-Berichts für einen Standort. Die Berichtsgenerierung führt mehrere LLM-Aufrufe je Engine/Prompt aus und läuft nie synchron innerhalb der Anfrage — dieser Aufruf reiht den Job ein und kehrt sofort zurück. Es gibt keine separate Job-ID oder Statusressource: Fragen Sie GET /api/v1/aeo/reports für denselben Standort per Polling ab und beobachten Sie das Feld generating, bis es wieder false liefert. Nicht verfügbar für Standorte, die älter sind als Synups Legacy-Standort-Cache (rein native Standorte).

AEO-Berichtsgenerierung einreihen

post/api/v1/aeo/reports/enqueue
aeo:write
Anfragetext
locationIdstringerforderlich
Der Standort, für den ein Bericht generiert werden soll.
clientIdstringoptional
Der Kunde des Standorts.
forcebooleanoptional
Bei true wird eine neue Generierung gestartet, auch wenn diesen Monat bereits ein Bericht generiert wurde.
Antwort
dataobjectoptional
enqueuedbooleanoptional
Immer true — der Generierungsjob wurde eingereiht.
forcebooleanoptional
Gibt das force-Flag aus der Anfrage zurück.
Fehler
400Der Anfrage fehlt ein erforderlicher Parameter, oder sie ist anderweitig fehlerhaft.
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
404Die Ressource wurde nicht gefunden oder gehört nicht zu Ihrer Agentur.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
post/api/v1/aeo/reports/enqueue
Ihr API-Schlüssel
Anfragetext*
{
  "data": {
    "enqueued": true,
    "force": false
  }
}
v1Ressourcen/AEO/getStandortübergreifendes AEO-Rollup abrufen

Liefert die neueste AEO-Berichtszusammenfassung je Standort, optional eingeschränkt auf einen Kunden und/oder Standort-Tags, plus portfolioweite Trend- und Systemfehler-Daten. Standorte ohne bisherigen Bericht zeigen null-Scores.

Standortübergreifendes AEO-Rollup abrufen

get/api/v1/aeo/rollup
aeo:read
Query-Parameter
clientIdstringoptional
Ergebnisse auf einen Kunden beschränken. Ist Ihr Schlüssel auf bestimmte Kunden beschränkt, ist dies erforderlich.
tagsstringoptional
Kommagetrennte Liste von Standort-Tag-Namen. Nur Standorte mit mindestens einem dieser Tags werden einbezogen.
Antwort
dataobjectoptional
rowsarray of objectoptional
Eine Zeile je Standort im Geltungsbereich.
locationIdstringoptional
Eindeutige Kennung des Standorts.
namestringoptional
Der Firmenname des Standorts.
citystringoptional
Stadt, oder null.
overallnumberoptional
Neuester Gesamt-KI-Sichtbarkeits-Score (0–100), oder null, falls nie generiert.
chatgptnumberoptional
Neuester ChatGPT-Score, oder null.
gemininumberoptional
Neuester Gemini-Score, oder null.
perplexitynumberoptional
Neuester Perplexity-Score, oder null.
generatedAtstringoptional
Wann der neueste Bericht generiert wurde, als ISO-8601-Zeitstempel, oder null, falls nie generiert.
yearMonthstringoptional
Monat des neuesten Berichts (YYYY-MM), oder null.
tagsarray of stringoptional
Die internen Tags des Standorts.
historyarray of numberoptional
Gesamt-Score-Historie für diesen Standort, chronologisch, nur Werte ungleich null.
deltanumberoptional
Veränderung des Gesamt-Scores gegenüber dem vorherigen Bericht, oder null beim ersten Bericht oder falls es keinen vorherigen Monat gibt.
topIssueobjectoptional
Der schwächste Sichtbarkeitsfaktor dieses Standorts, oder null, falls noch kein Bericht vorliegt.
labelstringoptional
tonestring (good | warn | bad)optional
configuredEnginesarray of string (ChatGPT | Gemini | Perplexity)optional
KI-Engines, für die diese Agentur einen API-Schlüssel konfiguriert hat.
portfolioHistoryarray of objectoptional
Durchschnittlicher Gesamt-Score über die Standorte im Geltungsbereich, je Monat.
yearMonthstringoptional
Monat im Format YYYY-MM.
avgnumberoptional
Durchschnittlicher Gesamt-Score über die berichtenden Standorte in diesem Monat.
locationsnumberoptional
Anzahl der Standorte mit einem Bericht in diesem Monat (der Nenner des Durchschnitts).
systemicFixesarray of objectoptional
Standortübergreifende Schwächen, die von mehreren Standorten geteilt werden, jeweils mit einer einzigen Sammelmaßnahme, sortiert nach Reichweite.
factorstringoptional
Maschinenlesbare Faktor-Kennung.
labelstringoptional
Für Menschen lesbarer Faktorname.
detailstringoptional
Erläuterung der systemischen Schwäche.
targetstring (listings | citations | reviews | posts | competitors | prompts)optional
Auf welchen Bereich des Produkts die Maßnahme verweist.
countnumberoptional
Anzahl der betroffenen Standorte.
pctnumberoptional
Prozentsatz der betroffenen berichtenden Standorte.
Fehler
401API-Schlüssel fehlt, ist ungültig, abgelaufen oder widerrufen.
403Dem Schlüssel fehlt die erforderliche Berechtigung, oder er ist für diesen Kunden/Standort nicht autorisiert.
429Zu viele Anfragen. Versuchen Sie es nach der im Retry-After-Header angegebenen Anzahl Sekunden erneut.
get/api/v1/aeo/rollup
Ihr API-Schlüssel
clientId
tags
{
  "data": {
    "rows": [
      {
        "locationId": "cm_loc_1",
        "name": "Acme Dental — Downtown",
        "city": "Austin",
        "overall": 62,
        "chatgpt": 68,
        "gemini": 56,
        "perplexity": null,
        "generatedAt": "2026-02-01T06:00:00.000Z",
        "yearMonth": "2026-02",
        "tags": [
          "priority"
        ],
        "history": [
          57,
          62
        ],
        "delta": 5,
        "topIssue": null
      }
    ],
    "configuredEngines": [
      "ChatGPT",
      "Gemini"
    ],
    "portfolioHistory": [
      {
        "yearMonth": "2026-01",
        "avg": 57,
        "locations": 5
      },
      {
        "yearMonth": "2026-02",
        "avg": 62,
        "locations": 5
      }
    ],
    "systemicFixes": [
      {
        "factor": "citations",
        "label": "Citations",
        "detail": "6 locations are missing citations on Yelp.",
        "target": "citations",
        "count": 6,
        "pct": 30
      }
    ]
  }
}