Marken- und Kategorie-Monitore
Ein Monitor hat einenmode, der beim Anlegen gesetzt wird und für seine gesamte Lebensdauer feststeht, weil er bestimmt,
was jede gespeicherte Antwort bedeutet.
Jede Antwort wird einmal bewertet, sobald sie eintrifft:
- Genannt: Einer Ihrer Aliase kommt im Antworttext vor.
positionist der Zeichen-Offset des ersten Treffers, odernull, wenn die Marke fehlt. - Zitiert: Die Antwort zitiert eine Seite auf einer Ihrer
domainsoder einer ihrer Subdomains. - Wettbewerbertreffer: Welche Wettbewerber des Monitors in derselben Antwort vorkommen.
analysis.
Schnellstart
1
Den Monitor anlegen
Der erste Lauf startet, sobald der Monitor angelegt ist.Die Antwort ist
201 mit dem gespeicherten Monitor. Merken Sie sich data.monitor.id.2
Auf die Antworten warten
Tasks werden zugelassen, soweit die Parallelität Ihres Tarifs es erlaubt, ein Lauf trifft also über Sekunden bis Minuten ein.
health.pending im Bericht zählt die noch laufenden Tasks. Lesen Sie den Bericht, sobald der Wert 0 erreicht.3
Den Bericht lesen
quality, dann stats, brands und opportunities. Jedes Feld wird in
Berichte und Metriken erklärt.POST /v1/monitors/{id}/run auf.
Einen Monitor anlegen
POST /v1/monitors (Referenz) prüft die Definition und die Limits Ihres
Kontos, speichert sie und startet den ersten Lauf. Der Aufruf liefert 201, bevor dieser Lauf abgeschlossen ist. Kann
der erste Lauf nicht starten (etwa weil Ihr Guthaben zu niedrig ist), wird der Monitor trotzdem angelegt, und der
Scheduler versucht den Lauf jede Minute erneut.
Die Anfrage aus dem Schnellstart liefert zum Beispiel:
Request-Felder
Jedes Listenfeld akzeptiert ein JSON-Array oder einen durch Zeilenumbrüche getrennten String. Einträge werden getrimmt, leere Einträge verworfen und Duplikate entfernt.Engines
Ein Monitor kann die prompt-basierten Antwort-Engines planen:CHATGPT, GEMINI, PERPLEXITY, GOOGLE
(Google AI Overviews), AIMODE (Google AI Mode), NAVER_AI_BRIEF, NAVER_AI_TAB und NAVER, einen
veralteten Namen, der für bestehende Monitore erhalten bleibt. Die Aliase GOOGLE_AIO, GOOGLE_AIMODE und
NAVER_AI_MODE werden akzeptiert und als GOOGLE, AIMODE und NAVER_AI_TAB gespeichert. Engine-Namen unterscheiden
Groß- und Kleinschreibung. Such-, Webdaten- und Analyse-Task-Typen wie GOOGLE_SERP oder CITATION_ANALYSIS
können nicht geplant werden. Preise und Details pro Engine stehen im Engine-Katalog.
Ein auf bestimmte Engines beschränkter API-Schlüssel kann nur Monitore anlegen, aktualisieren oder ausführen, die diese
Engines nutzen; alles andere liefert 403 KEY_SCOPE_DENIED.
Wettbewerber
Sie müssen keine Wettbewerber eintragen. Nach dem ersten Lauf liest eine wöchentliche Auswertung die letzten Antworten des Monitors und ergänzt die Marken, die dasselbe verkaufen wie Sie und in mindestens zwei Antworten vorkommen: bis zu 15 bei einem Marken-Monitor, 25 bei einem Kategorie-Monitor.- Gefundene Wettbewerber tragen
source: "auto", selbst eingetragenesource: "user". Die Auswertung ändert oder entfernt Ihre nie. Eine gefundene Marke, die die nächsten zwei Auswertungen beide nicht finden, wird entfernt. - Ändert sich die gefundene Liste, werden die gespeicherten Antworten des Monitors erneut dagegen bewertet, damit jede
Marke eines Berichts über dieselben Antworten gemessen wird.
competitorsReadAtzeigt, wann die letzte Auswertung lief. - Beim Update ersetzt
competitorsIhre eigene Liste und behält die gefundenen. Einträge mitsource: "auto"in der Anfrage werden ignoriert, Sie können also zurücksenden, wasGETgeliefert hat.
Wie Namen erkannt werden
- Der Abgleich ignoriert Groß- und Kleinschreibung sowie Zeichenbreite (NFKC).
- Namen in lateinischer Schrift werden nur als ganze Wörter erkannt: „replicates“ ist keine Nennung einer Marke namens Replicate. Ein koreanisches, japanisches, chinesisches oder thailändisches Zeichen direkt am Namen gilt als Wortgrenze, daher nennen „agoda를“ und „ahamoが“ agoda und ahamo. Koreanische, japanische, chinesische und thailändische Namen werden überall im Text erkannt.
- Ein Name aus einem Zeichen wird nie erkannt. Geben Sie einer solchen Marke einen längeren Alias.
- Überschneiden sich zwei Namen, zählt der früher beginnende, dann der längere. „Acme“ innerhalb eines Wettbewerbers namens „Acme Pro“ ist der Wettbewerber.
- Linkziele, nackte URLs und Zitations-Chips werden vor dem Abgleich entfernt; der sichtbare Text eines Links bleibt
erhalten. Eine Zitation zählt für
cited, nicht als Nennung.
Prompts schreiben, die etwas messen
- Ein Monitor pro Thema und Markt. „bestes CRM“ und „wie bepreise ich ein CRM“ sind verschiedene Absichten; wer sie mittelt, verdeckt beide.
- Formulieren Sie Prompts wie ein Käufer und nehmen Sie nie Ihre eigene Marke auf. Ein Prompt, der die Marke nennt, ist immer eine Nennung, meldet also 100 % und misst nichts. Wettbewerbernamen in Prompts sind in Ordnung.
Stichproben und Takt pro Engine
KI-Antworten ändern sich von Sitzung zu Sitzung, daher ist ein Anteil über mehrere Antworten stabiler als eine einzelne.engineSettings legt pro Engine fest, wie viele Antworten pro Prompt gesammelt werden und wie oft die Engine läuft:
samples: 1–10 Antworten pro Prompt und Punkt in jedem Lauf (Standard 1). Jede ist ein eigener Task in einer eigenen Sitzung, bewertet und abgerechnet wie jeder andere.intervalHours: ein Vielfaches desintervalHoursdes Monitors, bis 168. Die Engine nimmt an jedem k-ten Lauf teil, gezählt ab dem ersten Lauf, an dem jede Engine teilnimmt.
engineSettings den gespeicherten Wert; ein Update, das eine Engine entfernt, entfernt ihren Eintrag, und eines, das das
intervalHours des Monitors ändert, prüft die Engine-Intervalle gegen den neuen Wert.
Standort und Raster
Standardmäßig fragt jeder Task für das Land als Ganzes. Um lokale Antworten zu messen:locationstellt jeden Prompt von einem Punkt aus, in Dezimalgrad.gridstellt jeden Prompt von jedem Punkt eines quadratischen Rasters umcenteraus.sizeist die Zahl der Punkte pro Seite: 3, 5, 7 oder 9 (9 bis 81 Punkte).radiusMeters, 100 bis 50.000, ist der Abstand vom Mittelpunkt zur Mitte einer Kante.
CHATGPT, GEMINI, GOOGLE und AIMODE antworten für einen Standort. Ein Monitor mit Standort oder Raster und
einer anderen Engine wird mit 400 VALIDATION_ERROR abgelehnt. Beim Update löscht das Setzen von location oder
grid jeweils das andere, und null löscht den Wert. Die Antworten pro Punkt lesen Sie mit
GET /v1/monitors/{id}/grid.
Antwortseiten
Eine Antwort, deren Task eine Seite gespeichert hat, trägt deren Adresse indisplay.html, und das Panel liefert sie als Datei mit eingebetteten Schriften. Die Seite ist der echte Bildschirm des Motors, keine neue Darstellung des Markdown.
Monitorläufe fordern keine Seite an, ihre Antworten tragen also keine. Die Adresse wird trotzdem aus dem Task zurückgelesen, sobald einer eine Seite gespeichert hat; eine aufbewahrte Seite bleibt so aus ihrer Antwort erreichbar.
Kosten und Zeitplan
Ein Lauf erzeugt für jede teilnehmende Engine einen Task pro Prompt, pro Punkt und pro Stichprobe:points ist ohne Raster 1. Zum Beispiel ergeben 12 Prompts auf CHATGPT (1 Credit) und GOOGLE (1,25 Credits)
24 Tasks und 27 Credits pro Lauf, bei täglichem Intervall etwa 810 Credits im Monat. Mit
"CHATGPT": { "samples": 5 } sind es für denselben Monitor 72 Tasks und 75 Credits pro Lauf. Lesen Sie die aktuellen
Preise aus GET /v1/monitors/capabilities, statt sie fest zu codieren; wie Credits reserviert und
abgebucht werden, steht in Credits und Limits.
Zwei Posten kommen zu den Tasks hinzu:
- Wettbewerber-Auswertung: 80 Credits pro 30 Tage und Monitor, nach Takt auf die Läufe verteilt (etwa 2,67 Credits pro Lauf bei einem täglichen Monitor, 18,67 bei einem wöchentlichen). Berechnet wird, wenn alle Tasks eines Laufs eingereicht sind; ein Lauf, den Ihr Guthaben gestoppt hat, kostet dafür also nichts.
- Antwortanalyse: Mit
analysis: true1 Credit pro Task, berechnet nur für analysierte Antworten. Die Bewertungen (mentioned,cited,position) bleiben unverändert; das Ergebnis jeder Antwort steht inanswer.analysisvonGET /v1/monitors/{id}/answers/{taskId}.
location oder grid kostet pro Task 1 Credit zusätzlich.
Das Lesen von Berichten, Quellen, Antworten und Ergebnissen kostet nichts.
So verhält sich der Zeitplan:
- Ein Lauf ist kein Burst. Tasks werden eingereicht, soweit die Parallelität Ihres Tarifs und die Warteschlangen der Engines es erlauben. Jede Minute setzt der Scheduler dort fort, wo er angehalten hat, mit einem Task pro Engine im Wechsel, und Monitore verschiedener Konten wechseln sich ab. Ein Hauptkonto und seine Unterkonten teilen sich einen Satz von Durchgängen.
- Ein Lauf muss in sein Intervall passen. Können die Tasks einer Engine nicht zugelassen werden, bevor diese Engine
wieder läuft, liefern Anlegen und Update
400 VALIDATION_ERRORmit dem kürzesten passenden Intervall. Ein Lauf, der nach Ablauf eines ganzen Intervalls noch einreicht, wird geschlossen, und seine restlichen Tasks werden nicht gesendet. - Verpasste Läufe werden nicht nachgeholt.
nextRunAtist der Zeitpunkt, zu dem der nächste Lauf fällig wird. Das Fortsetzen eines pausierten Monitors oder eine Änderung vonintervalHoursplant den nächsten Lauf ein Intervall ab diesem Moment.
Capabilities
GET /v1/monitors/capabilities (Referenz) liefert für Ihr Konto:
jede planbare Engine mit creditsPerTask, analysisCreditsPerTask und placeCreditsPerTask, Ihre limits, die modes, die
Metrikdefinitionen (metrics), die Formeln des Zeitplans und die Typen der Änderungsereignisse. Der Aufruf hat keine
Nebenwirkungen und kostet nichts; rufen Sie ihn auf, bevor Sie Monitore programmatisch anlegen.
Prompts auswählen
Prompts aus Markenangaben vorschlagen
POST /v1/monitors/suggest (Referenz) liefert bis zu 12 Prompt-Kandidaten,
formuliert wie ein Käufer in country fragen würde. Es speichert nichts und verbraucht keine Credits.
429 RATE_LIMITED. Lehnt das Modell die Marke ab, liefert der Aufruf 400 SUGGEST_FAILED, fällt der
Vorschlagsdienst aus, 502 SUGGEST_FAILED, und ist er nicht konfiguriert, 503 SUGGEST_FAILED.
Prompts aus der Suchnachfrage recherchieren
POST /v1/monitors/research (Referenz) nimmt den Request-Body von
Prompt Research, kostet dieselben 14 Credits und liefert dasselbe Ergebnis als Task
Ihres Kontos.
data.task, dazu data.credits und data.replayed. Lesen Sie das
Ergebnis mit GET /v1/async/task/{id} und data.task.id (siehe Asynchrone Tasks).
Legen Sie dann den Monitor mit prompts[].prompt als prompts in ihrer Reihenfolge an; bei einem Kategorie-Monitor
den core jedes Prompts als seinen Eintrag in promptTopics, wenn die Recherche mehr als einen Core hat, und
brands[].brand als competitors. Gespeichert wird erst, wenn Sie den Monitor anlegen.
Ein Lauf darf höchstens so viele Tasks einreihen, wie das Limit tasksPerRun Ihres Kontos erlaubt, gezählt pro
Engine als Prompts × Standortpunkte × samples. Wählen Sie limit daher passend zum Monitor, den Sie anlegen. Siehe
Von der Recherche zum Monitor.
Kategorie-Monitore
Ein Kategorie-Monitor rankt die Marken, die die Engines für einen Markt nennen. Gruppieren Sie seine Prompts mitpromptTopics nach Teilbereichen:
aliases, domains und alertBelowPct müssen leer sein, sonst liefert
die Anfrage 400 VALIDATION_ERROR, und er hat keinen Alarm. Seine stats.mentioned und stats.cited in
GET /v1/monitors sind immer 0; die Liste ergänzt leader, die in den letzten 30 Tagen am häufigsten genannte
Marke. Sein Bericht ist in Kategorie-Berichte beschrieben. Zeitplan, Kosten,
Quellen, Antworten, Ergebnisse und Änderungsereignisse funktionieren wie bei einem Marken-Monitor, außer dass ein
Kategorie-Monitor nur Ereignisse vom Typ monitor.source.first_cited sendet.
Beim Update entfernt eine Änderung von prompts die promptTopics-Einträge entfernter Prompts. Die Antworten, die
diese Prompts gesammelt haben, bleiben im Ranking.
Monitore verwalten
Die ältere Periodenübersicht in
GET /v1/monitors/{id} bleibt aus Kompatibilitätsgründen erhalten. Für Zahlen nutzen Sie
/analytics: Die ältere Übersicht mischt eine Matrix der jeweils neuesten Antwort pro Prompt und
Engine über die gesamte Historie in die Fensterzahlen, kürzt Quellen auf 12 Domains und 20 Seiten, und ihr
shareOfVoice zählt jede Marke gegen alle Antworten, sodass die Anteile mehr als 100 ergeben können.
Ein Monitor eines anderen Kontos liefert 404 NOT_FOUND, nicht 403.
Einen Monitor aktualisieren
PATCH nimmt eine beliebige Teilmenge der Felder des Anlegens und prüft das Ergebnis als Ganzes gegen dieselben Limits.
Weggelassene Felder behalten ihre Werte.
enabled: falsepausiert den Monitor;enabled: truesetzt ihn fort, mit dem nächsten Lauf ein Intervall ab jetzt. Pausen erscheinen in Berichten alspauses.- Eine Änderung von
alertBelowPctmacht den Alarm wieder scharf. - Änderungen an Aliasen, Domains oder Wettbewerbern wirken auf Antworten, die ab dann bewertet werden. Gespeicherte Antworten behalten die Definitionen, mit denen sie bewertet wurden, daher halten Berichte Vergleiche über die Änderung hinweg zurück (siehe Berichte und Metriken).
Einen Monitor jetzt starten
POST /v1/monitors/{id}/run macht den nächsten Lauf sofort fällig; der Scheduler startet ihn innerhalb etwa einer
Minute, und der Aufruf liefert data.queued: true. Der Lauf wird wie ein geplanter abgerechnet. Ein erneuter Aufruf,
solange dieser Lauf noch fällig ist, erzeugt keinen zweiten Lauf.
Vor dem Einreihen prüft der Aufruf, ob Ihr Guthaben den Lauf deckt, einschließlich der Wettbewerber-Auswertung und der
Analyse-Credits. Wenn nicht, liefert er 402 INSUFFICIENT_CREDITS mit details.needed und details.available. Ein
Unterkonto über seinem monatlichen Credit-Limit erhält 429 SUB_ACCOUNT_CREDIT_LIMIT. Ein pausierter Monitor liefert
404 NOT_FOUND: Setzen Sie ihn zuerst fort.
Einen Bericht teilen
Sie können den Bericht eines Monitors unterhttps://querying.ai/<slug> veröffentlichen. Ein geteilter Bericht zeigt
Analysen, Quellen, Zitationen, Ergebnisse und Antworten; er zeigt nie Einstellungen, Alarme, die Laufsteuerung oder den
Task-Zustand Ihres Kontos.
GET /v1/monitors/{id}/share (Referenz) liefert den aktuellen Zustand,
access, slug, locale und url, dazu ein suggestedSlug, wenn keiner gesetzt ist.
PUT /v1/monitors/{id}/share (Referenz) ändert ihn:
access auf PRIVATE nimmt den Bericht offline und behält den Slug, sodass erneutes Teilen dieselbe Adresse
wiederverwendet.
Monitore aus einem Agenten nutzen
Der MCP-Server stellt Monitore als Tools bereit:get_monitor_capabilities, list_monitors,
get_monitor, create_monitor, update_monitor, delete_monitor, run_monitor,
get_monitor_analytics, get_monitor_sources, get_monitor_results, get_monitor_answer,
suggest_monitor_prompts, get_monitor_alerts und test_monitor_alert. Jedes macht einen API-Aufruf mit Ihrem
Schlüssel.
Ein praktischer Ablauf für einen Agenten oder ein Skript:
GET /v1/monitors/capabilities: Engines, Preise und Limits, bevor etwas ausgegeben wird.GET /v1/monitors: einen Monitor für Thema und Markt wiederverwenden oder einen anlegen, optional ausgehend vonPOST /v1/monitors/suggest.POST /v1/monitors/{id}/runnur, wenn Sie Antworten vor dem nächsten geplanten Lauf brauchen.GET /v1/monitors/{id}/analytics?days=30:qualityvor den Zahlen lesen und warten, bishealth.pending0erreicht.GET /v1/monitors/{id}/sources?days=30&groupBy=page:nextCursorbis zum Ende folgen.GET /v1/monitors/{id}/answers/{taskId}: die Antwort hinter dem obersten Eintrag inopportunitiesöffnen, bevor Sie darauf reagieren.GET /v1/monitors/{id}/results?since=...&until=...&format=csv: dasselbe Fenster exportieren undx-next-cursorfolgen, bis es leer ist.
Limits
Ein Vertragskonto ist ein Konto mit ausgehandeltem Parallelitätslimit. Diese Limits gelten für jedes Konto:
Limits für Berichte, Seitengrößen und Aufbewahrung stehen auf den Seiten, die sie betreffen:
Berichte und Metriken, Quellen und Antworten und
Ereignisse und Alarme.
Fehler
Die Fehlerhülle ist dieselbe wie überall (siehe Fehler). Monitor-spezifische Codes:Nächste Schritte
Berichte und Metriken
Der
/analytics-Vertrag und was jede Zahl bedeutet.Quellen und Antworten
Zitierte Seiten, die Antworten hinter jeder Bewertung und Exporte.
Ereignisse und Alarme
Webhooks, wenn sich Antworten ändern, und E-Mail-Alarme zu Ihrer Nennungsquote.
Prompt Research
Finden Sie die Prompts, die sich zu verfolgen lohnen, anhand der Suchnachfrage.