Zum Hauptinhalt springen
Sie legen einen Monitor einmal an. Jeder Lauf besteht aus gewöhnlichen asynchronen Tasks, abgerechnet zum Preis der jeweiligen Engine. Diese Seite behandelt das Anlegen, Ausführen und Verwalten von Monitoren. Wie Sie die Zahlen lesen, steht in Berichte und Metriken, die Antworten dahinter in Quellen und Antworten, Webhooks und E-Mail-Alarme in Ereignisse und Alarme. Die Dashboard-Ansicht derselben Daten finden Sie auf der Produktseite.

Marken- und Kategorie-Monitore

Ein Monitor hat einen mode, 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. position ist der Zeichen-Offset des ersten Treffers, oder null, wenn die Marke fehlt.
  • Zitiert: Die Antwort zitiert eine Seite auf einer Ihrer domains oder einer ihrer Subdomains.
  • Wettbewerbertreffer: Welche Wettbewerber des Monitors in derselben Antwort vorkommen.
Diese Bewertungen enthalten kein Sentiment und keine Schätzung des Marktanteils. Der Rang in einem Kategorie-Monitor ist ein Platz unter den Marken, die die Antworten nennen, nicht mehr. Für Sentiment und Empfehlungen pro Antwort aktivieren Sie 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

Lesen Sie zuerst quality, dann stats, brands und opportunities. Jedes Feld wird in Berichte und Metriken erklärt.
Um Antworten vor dem nächsten geplanten Lauf zu erhalten, rufen Sie 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 eingetragene source: "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. competitorsReadAt zeigt, wann die letzte Auswertung lief.
  • Beim Update ersetzt competitors Ihre eigene Liste und behält die gefundenen. Einträge mit source: "auto" in der Anfrage werden ignoriert, Sie können also zurücksenden, was GET geliefert 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 des intervalHours des Monitors, bis 168. Die Engine nimmt an jedem k-ten Lauf teil, gezählt ab dem ersten Lauf, an dem jede Engine teilnimmt.
Ein Eintrag darf nur eine der Engines des Monitors nennen und akzeptiert nur diese zwei Schlüssel. Beim Update ersetzt 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:
  • location stellt jeden Prompt von einem Punkt aus, in Dezimalgrad.
  • grid stellt jeden Prompt von jedem Punkt eines quadratischen Rasters um center aus. size ist 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.
Nur 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 in display.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: true 1 Credit pro Task, berechnet nur für analysierte Antworten. Die Bewertungen (mentioned, cited, position) bleiben unverändert; das Ergebnis jeder Antwort steht in answer.analysis von GET /v1/monitors/{id}/answers/{taskId}.
Ein Monitor mit location oder grid kostet pro Task 1 Credit zusätzlich. Das Lesen von Berichten, Quellen, Antworten und Ergebnissen kostet nichts.
Der Zeitplan wiederholt sich, bis Sie den Monitor pausieren oder löschen. Der obige Monatswert ist das, wozu Sie sich mit dem Anlegen verpflichten.
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_ERROR mit 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. nextRunAt ist der Zeitpunkt, zu dem der nächste Lauf fällig wird. Das Fortsetzen eines pausierten Monitors oder eine Änderung von intervalHours plant 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.
Zum Beispiel:
Vorschläge, die den Markennamen oder einen Alias enthalten, werden entfernt. Prüfen Sie die Liste, bevor Sie den Monitor anlegen. Sie können einen Vorschlag alle 20 Sekunden und 30 pro Stunde anfordern; darüber hinaus folgt 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.
Die Antwort enthält den eingereihten Task in 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 mit promptTopics nach Teilbereichen:
Ein Kategorie-Monitor hat keine eigene Marke: 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: false pausiert den Monitor; enabled: true setzt ihn fort, mit dem nächsten Lauf ein Intervall ab jetzt. Pausen erscheinen in Berichten als pauses.
  • Eine Änderung von alertBelowPct macht 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 unter https://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:
  1. GET /v1/monitors/capabilities: Engines, Preise und Limits, bevor etwas ausgegeben wird.
  2. GET /v1/monitors: einen Monitor für Thema und Markt wiederverwenden oder einen anlegen, optional ausgehend von POST /v1/monitors/suggest.
  3. POST /v1/monitors/{id}/run nur, wenn Sie Antworten vor dem nächsten geplanten Lauf brauchen.
  4. GET /v1/monitors/{id}/analytics?days=30: quality vor den Zahlen lesen und warten, bis health.pending 0 erreicht.
  5. GET /v1/monitors/{id}/sources?days=30&groupBy=page: nextCursor bis zum Ende folgen.
  6. GET /v1/monitors/{id}/answers/{taskId}: die Antwort hinter dem obersten Eintrag in opportunities öffnen, bevor Sie darauf reagieren.
  7. GET /v1/monitors/{id}/results?since=...&until=...&format=csv: dasselbe Fenster exportieren und x-next-cursor folgen, 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.