> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GEO-Monitoring-API: Markennennungen und Quellenangaben

> Prompt-Sets zeitgesteuert ausführen, einen Berichtsvertrag mit explizitem Nenner lesen und die Antworten hinter jeder Zahl exportieren.

Monitore führen ein gespeichertes Prompt-Set nach Zeitplan wiederholt aus und bewerten die resultierenden KI-Antworten
für Ihre Marke und deren Wettbewerber. Diese Seite ist der API-Vertrag: wie Sie einen Monitor konfigurieren, was jede
Zahl bedeutet, wie Sie die Quellen dahinter lesen und wie Sie die zugrunde liegenden Antworten exportieren. Für die
Dashboard-Ansicht derselben Daten beginnen Sie mit dem [Produktleitfaden](https://querying.ai/de/monitors).

Alle Schlüssel, ids, Marken und Prompts auf dieser Seite sind Platzhalter. Nichts davon ist ein echter Zugang oder ein echter Monitor.

## Was ein Monitor ist

Ein Monitor ist ein **benanntes Prompt-Set in einem Markt**: eine Liste von Prompts, die Engines, an die sie gehen, die
Aliase für „Ihre Marke“, optional Ihre Domains und einige Wettbewerber, ein Land und ein Intervall. Jeder geplante Lauf
reicht Prompts × Engines gewöhnliche asynchrone Tasks ein, und jede fertige Antwort wird einmal bewertet und aufbewahrt.

Die Bewertung ist bewusst eng gefasst, und die Daten können nicht mehr beantworten, als sie speichern:

* Sie hält fest, ob ein Marken-Alias im Antworttext vorkommt und an welchem Zeichen-Offset, ob die Antwort eine Ihrer
  registrierten Domains zitiert hat und welche Ihrer konfigurierten Wettbewerber in derselben Antwort vorkamen.
* Sie erzeugt **keinen** Sentiment-Wert und keine geschätzte Marktanteilszahl. Ein Rang ist ein Platz unter den
  Marken, die die Antworten nennen, wie im Ranking eines Kategorie-Monitors (siehe unten).

### Wettbewerber werden für Sie gefunden

Sie müssen keine Wettbewerber eintragen. Sobald der erste Lauf eines Monitors vorliegt, lesen wir seine letzten Antworten
mit einem Sprachmodell und behalten die Marken, die dasselbe verkaufen wie Sie und in mindestens zwei Antworten genannt
werden, höchstens 15. Das wiederholt sich alle 30 Tage, sodass neue Konkurrenten hinzukommen und nicht mehr genannte wegfallen.

* Gefundene Wettbewerber tragen `source: "auto"`. Selbst hinzugefügte tragen `source: "user"` und werden beim Lesen nie
  geändert oder entfernt.
* Ändert sich die gefundene Liste, werden die gespeicherten Antworten des Monitors neu dagegen gezählt, damit jede Marke
  eines Berichts über dieselben Antworten gemessen wird. `competitorsReadAt` am Monitor zeigt den letzten Lauf.
* Namen in lateinischer Schrift werden als ganze Wörter erkannt, „replicates“ ist also keine Nennung der Marke Replicate.

### Monitor-Sets bewusst aufteilen

Verschiedene Monitore stehen für verschiedene Themen oder Märkte und sind getrennte Berichte: Jeder hat sein eigenes
Fenster, seine eigene Bewertungsdefinition und seinen eigenen Zeitplan. Zwei Gewohnheiten zahlen sich aus:

* Ein Monitor pro Thema und Markt, damit die Kohorte eines Berichts vergleichbar bleibt. Wer „bestes CRM“ und „wie
  bepreist man ein CRM“ in ein Prompt-Set mischt, mittelt zwei verschiedene Absichten zu einer Zahl.
* Formulieren Sie Prompts wie ein Käufer und nehmen Sie nie Ihre eigene Marke auf. Ein Prompt mit der Marke ist immer
  eine Nennung, meldet also für immer 100 % und misst nichts. Wettbewerbernamen sind in Ordnung und oft die nützlichsten
  Prompts, die Sie schreiben können.

## Kategorie-Monitore: die Marken eines Marktes ranken

Ein Marken-Monitor verfolgt eine Marke. Ein **Kategorie-Monitor** verfolgt einen Markt: Sie benennen die Kategorie,
gruppieren ihre Fragen nach Teilbereichen, und der Bericht rankt die Marken, die die Engines in ihren Antworten nennen.
Setzen Sie beim Anlegen des Monitors `"mode": "CATEGORY"`. `mode` ist standardmäßig `BRAND` und bleibt über die gesamte
Lebensdauer des Monitors fest, weil es bestimmt, was jede gespeicherte Zeile bedeutet.

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

| Feld | Bei einem Kategorie-Monitor |
| - | - |
| `category` | Pflicht, 1–80 Zeichen: der Markt, wie ein Käufer ihn nennt. |
| `promptTopics` | Ordnet einen Prompt (seinen genauen Text) seinem Teilbereich zu. Bis zu 30 Teilbereiche mit höchstens 60 Zeichen. Ein Prompt ohne Eintrag deckt die ganze Kategorie ab. |
| `competitors` | Die zu rankenden Marken: bis zu 25, die Sie auflisten. Sobald der erste Lauf vorliegt, ergänzt das monatliche Auslesen bis zu 25 weitere, die die Antworten nennen. |
| `aliases` · `domains` · `alertBelowPct` | Lassen Sie sie leer. Ein Kategorie-Monitor hat weder eine eigene Marke noch eine eigene Domain noch einen Alarm, daher liefert ein Wert `400 VALIDATION_ERROR`. |

Zeitplan, Kosten, Fenster, Filter, `quality`, Quellen, Zitationen, Ergebnisse und Antworten funktionieren wie bei einem
Marken-Monitor. Ein Kategorie-Monitor hat keinen Alarm, daher liefert `POST /v1/monitors/{id}/alerts/test` `400`.

### Was der Bericht rankt

`GET /v1/monitors/{id}/analytics` liefert die Kategorie-Ansicht. `stats` und `previous` enthalten `runs`, `named`
(Antworten, die mindestens eine verfolgte Marke nennen) und `namedRate`; `changes.namedRatePp` ist die Änderung in
Punkten, und das Objekt `category` enthält das Ranking:

| Feld | Was es enthält |
| - | - |
| `category.brands` | Jede verfolgte Marke, die die Antworten genannt haben, die in den meisten Antworten genannte zuerst: `rank`, `mentions`, `sampleSize`, `mentionRate`, `shareOfVoice` und die Veränderung gegenüber dem vorherigen Intervall. |
| `category.topics` | Eine Zeile pro Teilbereich (`topic: null` ist die ganze Kategorie) mit `runs`, `namedRate` und den drei am häufigsten genannten Marken. |
| `category.engines` | Eine Zeile pro Engine mit den drei Marken, die sie am häufigsten nennt. |
| `category.series` | Pro UTC-Tag die Raten der fünf führenden Marken. |
| `category.prompts` | Eine Zeile pro Prompt mit seinen führenden Marken und den Zellen pro Engine; jede Zelle trägt eine `evidenceTaskId`, um die Antwort dahinter zu öffnen. |

* **`rank`** ordnet Marken nach der Zahl der Antworten, die sie nennen: Er ist ein Platz unter den Marken, die diese
  Antworten nennen. Eine Marke, die keine Antwort genannt hat, hat `rank: null`.
* **Die `mentionRate` einer Marke** teilt durch ihre eigene `sampleSize`, die Antworten, die bewertet wurden, während
  die Marke auf der Liste stand. Eine Marke, die Sie heute hinzufügen, wird ab heute gemessen.
* **`shareOfVoice`** ist `100 × Nennungen dieser Marke / alle Nennungen verfolgter Marken` im Fenster, die Anteile eines
  Fensters summieren sich also auf 100.
* `GET /v1/monitors` ergänzt bei jedem Kategorie-Monitor `leader` (die am häufigsten genannte Marke mit ihrer Rate).
  Seine Zähler `mentioned` und `cited` sind immer `0`.
* `GET /v1/monitors/{id}/answers/{taskId}` liefert `mode`, ein leeres `aliases` und die verfolgten Marken als
  `competitors`.

### Prompts aus der Suchnachfrage recherchieren

`POST /v1/monitors/research` nimmt den Request-Body von [Prompt Research](/de/research/prompt-research), kostet dieselben
12 Credits und liefert dasselbe Ergebnis, eingereicht für Ihr Konto. Lesen Sie den eingereihten Task mit
`GET /v1/async/task/{id}`; die ID steht in `data.task.id` der Antwort.

```bash theme={null}
curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'
```

Verwenden Sie `monitorSet.prompts` als `prompts`, das `topic` jedes Prompts als seinen Teilbereich in `promptTopics` und
`brands[].brand` als `competitors`. Die Schaltfläche **Recherche starten** im Dashboard tut dasselbe und füllt das
Formular; gespeichert wird erst, wenn Sie den Monitor anlegen.

## Kosten und Zeitplan

Ein Lauf reiht pro Prompt und Engine einen Task zum veröffentlichten Credit-Preis der jeweiligen Engine ein. Der
Zeitplan wiederholt sich, bis Sie den Monitor pausieren oder löschen. Beim Anlegen wählen Sie also laufende Kosten:

```text theme={null}
credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours
```

Zum Beispiel ergeben 12 Prompts auf ChatGPT (2 Credits) und Gemini (1 Credit) 24 Tasks und 36 Credits pro Lauf, bei
täglichem Intervall etwa 1.080 Credits im Monat. Lesen Sie die aktuellen Preise aus dem capabilities-Endpunkt, statt
sie fest zu codieren.

Zwei Eigenschaften des Zeitplans sollten Sie kennen, bevor Sie sich darauf verlassen:

* Ein Lauf ist **kein** Burst. Tasks werden zugelassen, soweit Tarif-Parallelität und Warteschlange es erlauben. Ein
  Lauf über dem Limit eines Gratis-Tarifs trifft daher über mehrere Minuten ein, statt verworfen zu werden. Beobachten
  Sie `health.pending` in einem Bericht, um einen laufenden Durchgang zu sehen.
* Das nächste Fenster ist ein Zeitpunkt, keine Garantie. `nextRunAt` ist der Fälligkeitszeitpunkt. Ein eine Woche lang
  pausierter Monitor läuft ein Intervall nach der Reaktivierung weiter, statt die verpassten Läufe nachzuholen.

Das Finden Ihrer Wettbewerber kostet 100 Credits pro Monat und Monitor, nach Intervall auf die Läufe verteilt:
etwa 3 Credits pro Lauf bei täglichem, etwa 23 bei wöchentlichem Intervall. Berechnet wird erst, wenn alle Tasks
eines Laufs eingereiht sind; ein Lauf, den Ihr Guthaben gestoppt hat, kostet dafür nichts.

## Endpunkte

| Methode und Pfad | Was Sie erhalten |
| - | - |
| `GET /v1/monitors/capabilities` | Engines mit Credit-Preisen, Limits, Metrikdefinitionen und der Kostenrechnung des Zeitplans. Ein günstiger Lesezugriff ohne Nebenwirkungen. |
| `GET /v1/monitors` | Ihre Monitore mit je einer 30-Tage-Übersicht. |
| `POST /v1/monitors` | Einen Monitor anlegen und starten. |
| `GET /v1/monitors/{id}` | Veraltete Periodendetails. Nutzen Sie stattdessen `/analytics`: Dieser Endpunkt mischt eine ungefilterte Zellmatrix über die gesamte Historie in die Fensterzahlen und kürzt Quellen auf 12 Domains und 20 Seiten. |
| `PATCH /v1/monitors/{id}` | Felder aktualisieren oder mit `enabled` pausieren und fortsetzen. |
| `DELETE /v1/monitors/{id}` | Den Monitor und seine Bewertungshistorie löschen. |
| `POST /v1/monitors/{id}/run` | Den nächsten Lauf auf jetzt vorziehen. Er verbraucht Credits wie jeder Lauf. |
| `GET /v1/monitors/{id}/analytics` | **Der Berichtsvertrag.** Eine Kohorte, ein Filtersatz, alle Abschnitte. |
| `GET /v1/monitors/{id}/sources` | Zitierte Domains oder Seiten für dasselbe Fenster, paginiert. |
| `GET /v1/monitors/{id}/citations` | Tägliche Zitationsreihe für die wichtigsten Domains und Seiten: die Daten hinter den Zitationsdiagrammen im Dashboard. |
| `GET /v1/monitors/{id}/results` | Die bewerteten Zeilen selbst, als JSON oder CSV, mit Filtern und Cursor. |
| `GET /v1/monitors/{id}/answers/{taskId}` | Die aufbewahrte Antwort hinter einer Zeile. |
| `GET /v1/monitors/{id}/prompt` | Detailansicht eines Prompts: seine Zeitreihe, Quellen und neueste Zeilen. |
| `GET /v1/monitors/{id}/alerts` · `POST .../alerts/test` | Alarmschwelle, Latch-Status und Zustellhistorie; eine Test-E-Mail einreihen. |
| `POST /v1/monitors/suggest` | Vorschläge für Prompts aus Markenangaben. Speichert nichts und verbraucht keine Task-Credits. |
| `POST /v1/monitors/research` | Prompts für einen Monitor recherchieren: Anfrage, Preis und Ergebnis von [Prompt Research](/de/research/prompt-research), eingereicht für Ihr Konto. |

Alle verwenden denselben Bearer-Schlüssel wie der Rest der API (siehe [Authentifizierung](/de/authentication)). Ein
Monitor eines anderen Kontos antwortet mit `404`, nicht `403`.

## Einen Monitor anlegen

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

`name`, `engines`, `prompts`, `aliases` und `intervalHours` sind bei einem Marken-Monitor Pflicht; ein Kategorie-Monitor nimmt statt `aliases` das Feld `category`. Jede Liste akzeptiert ein Array oder einen
durch Zeilenumbrüche getrennten String; Einträge werden getrimmt, Leerzeilen verworfen und Duplikate entfernt.
`country` wählt den Markt, für den die Engines antworten, und übersetzt die Prompts nicht. `prompts × engines` muss
höchstens dem `tasksPerRun`-Limit aus capabilities entsprechen.

Engines sind die planbaren Prompt-Oberflächen: `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`,
`NAVER_AI_BRIEF`, `NAVER_AI_TAB` und der veraltete Alias `NAVER`. `GOOGLE_AIO` und `GOOGLE_AIMODE` werden akzeptiert und
als `GOOGLE` und `AIMODE` gespeichert. Analyse-Tasks wie `SOURCE_INFLUENCE` sind keine Prompt-Oberflächen und können
nicht in einem Monitor geplant werden.

Ein auf bestimmte Engines beschränkter Schlüssel kann nur diese Engines planen; alles andere ist
`403 KEY_SCOPE_DENIED`. Das Monitor-Limit des Kontos liefert `409 MONITOR_LIMIT`.

## Ausführen, dann den Bericht lesen

`POST /v1/monitors/{id}/run` macht den nächsten Lauf sofort fällig, und die Antwort-Tasks erscheinen innerhalb etwa
einer Minute. Er wird wie ein geplanter Lauf abgerechnet, und ein erneuter Aufruf, solange dieses Fenster noch fällig
ist, wird nicht doppelt berechnet.

`GET /v1/monitors/{id}/analytics` ist der Vertrag, aus dem jeder Teil Ihres Berichts stammen sollte. Sein Fenster ist
**halboffen und in UTC** (`since` inklusive, `until` exklusive), und Sie wählen es auf eine von zwei Arten:

| Parameter | Regel |
| - | - |
| `days` | Einer der Werte `7`, `30` (Standard) oder `90`, endet jetzt. Nicht mit `since`/`until` kombinierbar. |
| `since` und `until` | Nur zusammen, als vollständige ISO-Zeitpunkte **mit Zeitzone** (zum Beispiel `2026-09-15T00:00:00Z`). Die Spanne muss positiv sein, höchstens 90 Tage betragen und darf nicht in der Zukunft liegen. Ein bloßes `YYYY-MM-DD` wird hier abgelehnt, da es kein portables Fenster definiert. |

Zwei optionale Filter gelten gleichzeitig für **alle** Abschnitte: `engine` (kanonische id oder öffentlicher Alias)
und `prompt` (exakter Text, bis 2.000 Zeichen). Zeilen sind nach Prompt-Text indiziert, sodass ein später aus dem
Monitor entfernter Prompt abfragbar bleibt.

Alle Abschnitte teilen diese eine Kohorte, und das vorherige Intervall hat exakt dieselbe Dauer und dieselben Filter.
Der Vergleich erfolgt also unter gleichen Bedingungen:

| Feld | Inhalt |
| - | - |
| `window` | `since`, `until`, `previousSince`, `previousUntil`, `timezone` und die wörtlichen `bounds` des Fensters. `previousUntil` ist immer das `since` dieses Fensters. |
| `filters` | Die angewandten, aufgelösten Filter: die kanonische Engine-id, der exakte Prompt oder `null`. |
| `stats` · `previous` | Zählwerte und Quoten für das Fenster und das Intervall davor. |
| `changes` | Veränderungen in Prozentpunkten oder `null`, wenn der Vergleich nicht belastbar ist (siehe unten). |
| `engineRates` | Dieselben Quoten pro Engine, damit eine schwache Engine ohne Diagramm sichtbar ist. |
| `series` | Pro UTC-Tag und Engine, wobei `partial` einen vom Fensterrand abgeschnittenen Tag markiert. |
| `brands` | Ihre Marke (`__you__`) und jeder beobachtete Wettbewerber, nach Nennungen absteigend, jeweils mit eigener `sampleSize` und der darauf gemessenen Quote. |
| `voiceSeries` | Dieselben Marken pro UTC-Tag, für die Trendlinie. |
| `prompts` | Summen pro Prompt, schwächste Nennungsquote zuerst, jeweils mit Zellen pro Engine. |
| `opportunities` | Zellen, in denen ein Wettbewerber genannt wurde und Ihre Marke nicht, meiste Fehlstellen zuerst. Die Liste, mit der Sie arbeiten. |
| `quality` | Woraus die Stichprobe besteht und alles, was die Zahlen nicht aussagen können. |
| `health` · `healthScope` | Laufzustand für Tasks, die noch einzeln sichtbar sind: ein separater aktueller Bereich, nie Teil des Nenners. |

## Was die Zahlen bedeuten

Lesen Sie dies, bevor Sie ein Dashboard-Panel beschriften. Die Definitionen sind der veröffentlichte Vertrag, und
`GET /v1/monitors/capabilities` liefert sie als `metrics`, damit ein Client sie neben den Zahlen anzeigen kann.

* **`mentionRate`** für das Fenster, seine Engine-Gruppen und seine Zell-Gruppen ist
  `100 × Antworten mit Nennung / bewertete Antworten`. Sie ist nach Antworten gewichtet, kein Mittelwert der
  Engine-Quoten, sodass eine vielgenutzte Engine nicht von einer wenig genutzten überstimmt wird. (Die eigene Quote
  einer Marke hat einen eigenen Nenner, siehe nächster Punkt.)
* **`citationRate`** hat dieselbe Form für Antworten, die eine Ihrer registrierten Domains zitiert haben. Ohne
  registrierte Domains ist sie immer null, weil die Quellenverfolgung aus ist.
* **Die Quote einer Marke teilt durch ihre eigene `sampleSize`, nicht durch die Fenstersumme.** Für Ihre Marke sind
  das alle bewerteten Antworten; für einen Wettbewerber nur die Antworten, die bewertet wurden, während er im Monitor
  war. Fügen Sie heute einen Wettbewerber hinzu, deckt sein erster Bericht die Antworten ab, die ihn gemessen haben:
  Die Zeit vor seiner Aufnahme zählt nicht gegen ihn. Eine Marke ohne passende Antworten meldet
  `mentionRate: null`, nicht 0 %, weil 0 % wie ein echtes Verschwinden wirken würde.
* **`shareOfVoice`** in `brands` ist `100 × Nennungen dieser Marke / alle Nennungen beobachteter Marken` im Fenster, die
  Anteile eines Fensters ergeben also zusammen 100. Es vergleicht Marken innerhalb der Antworten, **die Sie für diese
  Prompts gesammelt haben**; es ist weder Marktanteil noch Sichtbarkeitsranking. Das `shareOfVoice` des veralteten
  Detail-Endpunkts ist die ältere Sicht der Antwortdurchdringung, bei der jede Marke gegen die gesammelten Antworten
  gezählt wird und die Summe über 100 liegen kann. Mischen Sie beides nicht in einem Diagramm.
* **`competitorOnly`** (und die Liste `opportunities`) zählt Antworten, die einen konfigurierten Wettbewerber nannten,
  während Ihre Marke fehlte. Das ist die Lücke, an der Sie ansetzen können.
* **Quoten sind nullbar, nicht null.** Keine Antworten im Fenster ergibt `null`; eine Quote von null bedeutet, dass es
  Antworten gab und keine passte.
* **Eine abgeschlossene Beobachtung ohne Antwort zählt als nicht genannt.** Sie bleibt im Nenner, und
  `quality.noAnswerObservations` gibt an, wie viele es waren. Ein **fehlgeschlagener** Task wird aus allen Quoten
  ausgeschlossen und erscheint nur in `health`. Eine defekte Engine verkleinert die Stichprobe, statt stillschweigend
  zu einer Abwesenheit zu werden, und `quality` rekonstruiert sie nie als solche (`historicalFailures` ist immer `null`).
* **Veränderungen werden zurückgehalten, wenn sie irreführen würden.** `changes` und das `mentionRateChangePp` pro Zelle
  sind `null`, und `quality.comparable` ist `false`, wenn eine Periode keine Antworten hat (`insufficient_periods`),
  wenn Zeilen bewertet wurden, bevor es einen Bewertungskontext gab (`legacy_scoring_unknown`), oder wenn sich die
  Bewertungsdefinition zwischen den Perioden geändert hat (`scoring_definitions_changed`). Historische Zeilen behalten
  die Definitionen, mit denen sie bewertet wurden (`quality.scoring`). Änderungen an Aliasen oder Wettbewerbern
  schreiben die Vergangenheit also nie um. Einzige Ausnahme ist das oben beschriebene monatliche Lesen der Wettbewerber.
* **Die Stichprobengröße wird veröffentlicht.** `quality.lowSample` ist unter 30 bewerteten Antworten true,
  `quality.missingCells` zählt konfigurierte Prompt × Engine-Zellen ohne bisherige Antworten, und `quality.partialDays`
  nennt die UTC-Tage, die das Fenster halbiert. Der niedrigere Zählwert eines Teiltags ist Arithmetik, kein Rückgang.

`position` in einer bewerteten Zeile ist der **Zeichen-Offset** des frühesten Alias-Treffers im Antworttext: ein
Näherungswert für Prominenz, kein Ranking. Er ist `null`, wenn die Marke fehlte, weshalb `0` nie „fehlt“ bedeuten muss.

## Woher die Antworten kommen

`GET /v1/monitors/{id}/sources` beantwortet die Frage „Welche Seiten gewinnen diese Prompts?“ mit demselben Fenster und
denselben Filtern wie der Bericht und zählt **verschiedene Antworten** statt roher Quellenangaben. Eine Seite, die in
einer Antwort dreimal zitiert wird, zählt also einmal.

| Parameter | Regel |
| - | - |
| `groupBy` | `domain` (Standard, Host ohne `www.`) oder `page` (vollständige URL mit Label). |
| `limit` | 1–100, Standard 20. |
| `cursor` | Das `nextCursor` der vorherigen Antwort, unverändert zurückgegeben. `null` beendet die Liste. |
| `days` / `since`+`until` / `engine` / `prompt` | Genau wie beim Bericht. |

Jede Zeile enthält `citations` und `prompts` (beides Zählungen verschiedener Antworten), `own` für Ihre registrierten
Domains und eine `evidenceTaskId`, die Sie mit dem Antwort-Endpunkt öffnen können. Hier gibt es keine stille
Top-N-Kürzung: Jede Domain oder Seite im Fenster ist über den Cursor erreichbar.

## Zitationen im Zeitverlauf

`GET /v1/monitors/{id}/citations` liefert die Daten hinter den Zitationsdiagrammen im
Dashboard: die täglichen Zitationssummen des Zeitfensters und eine tägliche Reihe für jede
führende Domain und Seite. Es liest nur gespeicherte Ergebnisse und verbraucht daher keine Credits.

| Parameter | Regel |
| - | - |
| `days` | `7`, `30` oder `90`, Standard `30`. |
| `since`+`until` | Ein festes Fenster von höchstens 90 Tagen, wie beim Report. Wenn gesetzt, ist `days` nur eine Anzeigebeschriftung. |
| `engine` / `prompt` | Wie beim Report. |
| `kind` | `all` (Standard), `owned`, `editorial`, `pr_wire`, `institution`, `reviews`, `commerce`, `social`, `other`. |
| `q` | Filtert Domains nach Name oder Seiten nach URL. Höchstens 200 Zeichen. |
| `offset` | 0–10.000. Jede Liste liefert 20 Zeilen. |

Eine Zitation ist hier eine Seite, die in einer Antwort vorkommt; dieselbe Seite zweimal in
einer Antwort zählt einmal. `/sources` zählt stattdessen unterschiedliche Antworten, daher
können die Zahlen abweichen.

| Feld | Bedeutung |
| - | - |
| `totals` | `answers`, `citedAnswers`, `citations` und `ownedCitations` für das Fenster. |
| `days` | Ein Eintrag pro gemessenem UTC-Tag mit `answers`, `citations` und `ownedCitations`. Ein Tag mit Antworten, aber ohne Zitationen erscheint mit `citations: 0`; ein Tag ohne Antworten fehlt. |
| `domains` / `pages` | Die Top 20 beim aktuellen `offset`, jeweils mit `kind`, `owned`, `citations`, `answers`, `prompts` und einer `daily`-Reihe aus `{day, citations}`. `daily` enthält nur Tage mit Zitationen. |
| `types` | Zitationen und unterschiedliche Domains je `kind`, über alle Quellen. |
| `pagination` | `offset`, `limit`, `totalDomains`, `totalPages`. |

Der Anteil einer Quelle ist ihr `citations` geteilt durch `totals.citations`. `kind`, `q`
und `offset` schränken nur die Listen ein; `totals`, `days` und `types` umfassen immer alle
Quellen im Fenster.

```bash theme={null}
curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

## Die bewerteten Zeilen exportieren

`GET /v1/monitors/{id}/results` liefert die Zeilen selbst, für einen Data-Warehouse-Import, eine Wochenpräsentation
oder eine Tabelle.

| Parameter | Regel |
| - | - |
| `since` · `until` | Halboffen, standardmäßig die letzten 30 Tage bis jetzt. `since` akzeptiert aus Kompatibilität mit dem ursprünglichen Export auch ein bloßes `YYYY-MM-DD` (gelesen als `00:00:00Z`); der Berichtsendpunkt nicht. |
| `engine` · `prompt` | Dieselben Filter wie beim Bericht. |
| `mentioned` · `cited` | `true`/ `false`. `mentioned=false` ist die Ansicht der Wettbewerbslücken. |
| `competitor` | Ein exakter konfigurierter Wettbewerbername; behält Antworten, deren gespeicherte Wettbewerberliste ihn enthält. |
| `includeEvidence` | Fügt jeder Zeile `answerText`, `sources` und `scoringContext` hinzu und senkt die Obergrenze der Seitengröße. |
| `limit` | 1–10.000, Standard 10.000. Mit `includeEvidence` sind Standard und Maximum 100. |
| `format` | `json` (Standard) oder `csv`. |
| `cursor` | Das `nextCursor` der vorherigen Antwort. |

Die Paginierung ist ein Keyset über `(ranAt, id)` mit Mikrosekundengenauigkeit, sodass Zeilen mit gleichem Zeitstempel
weder übersprungen noch wiederholt werden können. Um die Extraktion reproduzierbar zu machen: **Senden Sie explizite
Werte für `since` und `until`, halten Sie sie fest und folgen Sie `nextCursor`, bis er `null` ist.** Wird das Fenster
zwischen den Seiten geändert, können Zeilen übersprungen oder wiederholt werden. Behandeln Sie den Cursor als
undurchsichtig: Er wird zurückgegeben und weitergereicht, nie selbst gebaut.

Mit `format=csv` ist die Antwort `text/csv` (UTF-8 mit BOM, damit Excel sie korrekt öffnet), und der
Paginierungsstatus wandert in die Header, weil ein CSV-Body keinen anderen Platz dafür hat:

| Header | Bedeutung |
| - | - |
| `x-next-cursor` | Der Cursor für die nächste Seite; auf der letzten Seite leer. |
| `x-result-truncated` | `true`, wenn mehr Zeilen passten, als diese Seite geliefert hat. |
| `x-result-since` · `x-result-until` | Das aufgelöste Fenster, damit ein fortgesetzter Export es festhalten kann. |

Die Spalten sind `ran_at, monitor, engine, prompt, mentioned, cited, position, competitors, task_id`, dazu
`answer_text, sources, scoring_context` bei `includeEvidence=true` (`sources` und `scoring_context` als JSON-Text in
ihren Zellen). Zellen, die als Tabellenformel gelesen werden könnten, werden vor dem Schreiben entschärft, sodass
fremder Text in Ihrer Tabelle nicht zur Formel wird.

## Die Antwort hinter einer Zahl lesen

`GET /v1/monitors/{id}/answers/{taskId}` liefert den aufbewahrten Beleg für eine Zeile:

* `answerText`: die Antwort, wie die Engine sie gegeben hat, wenn möglich als Markdown, **höchstens 8.000 Zeichen**,
  bei größerer Länge mit Auslassungszeichen gekürzt.
* `sources`: die Quellenangaben in der Reihenfolge der Engine, jeweils mit Label und 1-basierter Position in dieser Liste.
* `aliases` und `competitors`: womit diese Zeile abgeglichen wurde, damit die Nennung geprüft statt einfach geglaubt werden kann.
* `scoringContext`: die exakt verwendete Definition, mit `version`-Hash, Bewertungszeit, `answerPresent` und
  `evidenceTruncated`, wenn der Text oben gekürzt wurde.

Zeilen, die bewertet wurden, bevor ein Bewertungskontext gespeichert wurde, liefern `scoringKnown: false` mit den
aktuellen Aliasen des Monitors und einem `evidenceTruncated` von `null`. `answerText` ist `null`, wenn die Engine keinen
Antworttext geliefert hat.

## Fehler auf dieser Oberfläche

Der Umschlag ist derselbe wie überall (siehe [Fehler](/de/concepts/errors)); die für das Monitoring spezifischen Codes sind:

| Code | Status | Wann |
| - | - | - |
| `VALIDATION_ERROR` | 400 | Ungültiges Fenster (`days` gemischt mit `since`/`until`, eine Spanne über 90 Tage, ein Zeitpunkt ohne Zeitzone), eine unbekannte Engine, ein zu langer Prompt, ein `limit` außerhalb des Bereichs oder ein Bericht, der zu groß zum Aggregieren ist: Fenster, Engine oder Prompt eingrenzen. |
| `MISSING_API_KEY` / `UNAUTHORIZED` | 401 | Kein Schlüssel oder ein Schlüssel, der nicht zu diesem Konto gehört. |
| `KEY_SCOPE_DENIED` | 403 | Die erlaubten Engines des Schlüssels decken die Engines des Monitors nicht ab. |
| `NOT_FOUND` | 404 | Kein solcher Monitor für diesen Schlüssel (der Monitor einer anderen Person sieht genauso aus) oder keine bewertete Zeile mit dieser Task-id. |
| `MONITOR_LIMIT` | 409 | Das Konto hat bereits die maximale Anzahl an Monitoren. |
| `RATE_LIMITED` | 429 | Prompt-Vorschläge (einer pro 20 Sekunden, 30 pro Stunde) oder Test-Alarm-E-Mails (drei pro Monitor alle fünf Minuten). |
| `SUGGEST_FAILED` | 400 / 502 / 503 | Prompt-Vorschläge wurden für diese Marke abgelehnt, der Vorschlagsdienst ist fehlgeschlagen oder auf diesem Deployment nicht konfiguriert. |

## Ein Agent im Ablauf

Eine praktische Abfolge für einen Agenten oder ein Skript, nur mit den Endpunkten dieser Seite. Sie dient zur
Veranschaulichung: Setzen Sie Ihren eigenen Schlüssel, Ihre Monitor-id und Ihr Fenster ein.

1. `GET /v1/monitors/capabilities`: Engines, Preise und Limits lesen, bevor etwas ausgegeben wird.
2. `GET /v1/monitors`: einen vorhandenen Monitor für Thema und Markt wiederverwenden oder mit `POST /v1/monitors` einen
   anlegen (optional zuerst `POST /v1/monitors/suggest` aufrufen und die Vorschläge bearbeiten).
3. `POST /v1/monitors/{id}/run`: falls Sie Antworten vor dem nächsten geplanten Fenster brauchen.
4. `GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT`: zuerst `quality` lesen (`comparable`, `lowSample`,
   `missingCells`, `partialDays`), dann die Zahlen. Pollen, bis `health.pending` sich beruhigt und
   `quality.sampleSize` nicht mehr wächst.
5. `GET /v1/monitors/{id}/sources?days=30&groupBy=page`: mit `nextCursor` blättern, um die Seiten zu finden, die die Prompts gewinnen.
6. `GET /v1/monitors/{id}/answers/{taskId}`: die Antwort hinter dem obersten Eintrag in `opportunities` öffnen, bevor etwas entschieden wird.
7. `GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv`: dasselbe Fenster exportieren
   und `x-next-cursor` folgen, bis er leer ist.

Dieselben Operationen stehen Agenten als MCP-Tools zur Verfügung (`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`,
`test_monitor_alert`). Schreibvorgänge sind als Mutationen gekennzeichnet, und `create_monitor` und `run_monitor` geben
vor dem Aufruf an, dass sie Credits verbrauchen.

## Limits

| Limit | Wert |
| - | - |
| Monitore pro Konto | 20 |
| Tasks pro Lauf | 200 (`prompts × engines`) |
| Prompts pro Monitor | 100 |
| Prompt-Länge | 2.000 Zeichen |
| Marken-Aliase | 20 |
| Registrierte Domains | 20 |
| Wettbewerber | Marken-Monitor: 10 eigene, dazu bis zu 15 gefundene. Kategorie-Monitor: 25 eigene, dazu bis zu 25 gefundene |
| Kategoriename | 80 Zeichen |
| Teilbereiche pro Kategorie-Monitor | 30, je höchstens 60 Zeichen |
| Intervall | 1–168 Stunden |
| Berichtsfenster | 90 Tage |
| Ergebnisseite | Standard 10.000, maximal 10.000; 100 mit Belegen |
| Quellen- oder Belegseite | 100 |

Sehen Sie sich die [Preise](https://querying.ai/de/pricing) und die [Engine-Referenz](/de/engines/overview) an, bevor Sie das Volumen erhöhen.