Zum Hauptinhalt springen
GET /v1/monitors/{id}/analytics (Referenz) liefert jede Zahl im Bericht eines Monitors aus einem Satz von Antworten: ein Fenster, ein Filtersatz und dasselbe Fenster davor zum Vergleich. Bauen Sie jedes Panel Ihres eigenen Berichts aus diesem Endpunkt und lesen Sie quality vor den Zahlen. Das Lesen eines Berichts kostet nichts.

Query-Parameter

Das Fenster ist halboffen und in UTC: since ist enthalten, until nicht. Das vorherige Fenster hat exakt dieselbe Länge, endet bei since und nutzt dieselben Filter, jeder Vergleich erfolgt also unter gleichen Bedingungen. Senden Sie jeden Parameter einmal.

Beispiel

Ein Marken-Monitor, der ChatGPT einmal täglich zwei Prompts mit samples: 5 stellt (zehn Antworten pro Tag), gefiltert auf ChatGPT über zwei Tage, liefert zum Beispiel:
So lesen Sie es: Die Marke wurde in 9 von 20 ChatGPT-Antworten genannt (45 %), 15 Punkte weniger als in den zwei Tagen davor. Northwind Audio wurde in mehr Antworten genannt, und „are cheap earbuds worth it“ ist der schwächste Prompt, mit 4 Antworten, die einen Wettbewerber nannten und die Marke nicht. quality.lowSample ist true, behandeln Sie die Veränderung also als Anlass zur Prüfung, nicht als Trend.

Abschnitte der Antwort

Quotenobjekte

stats, previous, jeder Eintrag in engineRates und series, jeder Prompt und jede Zelle tragen dieselben Felder:

Zellen

Eine Zelle ist ein Prompt auf einer Engine. Neben dem Quotenobjekt und previous trägt sie: Jede id ist null, wenn keine Antwort infrage kommt. Öffnen Sie eine mit GET /v1/monitors/{id}/answers/{taskId}.

Marken und Share of Voice

Jeder Eintrag in brands hat name, mentions, sampleSize, mentionRate, shareOfVoice, previousMentionRate, previousShareOfVoice und configured (false für eine im Fenster genannte Marke, die nicht mehr am Monitor ist).

Was die Zahlen bedeuten

GET /v1/monitors/capabilities liefert diese Definitionen als metrics, damit ein Client sie neben den Zahlen anzeigen kann.
  • mentionRate ist 100 × mentioned / bewertete Antworten, für das Fenster, jede Engine, jeden Tag und jede Zelle. Sie ist nach Antworten gewichtet, kein Mittelwert über Engines, sodass eine vielgenutzte Engine nicht von einer wenig genutzten überstimmt wird.
  • citationRate hat dieselbe Form für Antworten, die eine Ihrer Domains zitierten. Ohne Domains ist sie immer 0, weil die Zitationsverfolgung aus ist.
  • Die Quote einer Marke teilt durch ihre eigene sampleSize. Für Ihre Marke sind das alle bewerteten Antworten. Für einen Wettbewerber nur die Antworten, die bewertet wurden, während er am Monitor war; ein heute hinzugefügter Wettbewerber wird also ab heute gemessen. Die mentionRate eines Wettbewerbers ist null, wenn einige Antworten im Fenster bewertet wurden, bevor der Bewertungskontext gespeichert wurde, weil unbekannt ist, wogegen sie abgeglichen wurden.
  • shareOfVoice ist 100 × Nennungen dieser Marke / alle Nennungen verfolgter Marken im Fenster, die Anteile eines Fensters ergeben also zusammen 100 (quality.trackedBrandMentions ist der Nenner). Es vergleicht Marken innerhalb der Antworten, die Sie für diese Prompts gesammelt haben. Es ist weder Marktanteil noch ein Sichtbarkeitsranking.
  • competitorOnly und opportunities zählen Antworten, die einen Wettbewerber nannten, während Ihre Marke fehlte: die Lücke, an der Sie ansetzen können.
  • null ist nicht 0. Eine Quote ist null, wenn es keine Antworten gab, durch die geteilt werden könnte. 0 bedeutet, dass es Antworten gab und keine passte.
  • Eine Antwort ohne Text zählt als nicht genannt. Ein abgeschlossener Task ohne Antwort bleibt im Nenner; quality.noAnswerObservations zählt sie. Ein fehlgeschlagener Task wird aus allen Quoten ausgeschlossen und erscheint nur in health. Eine defekte Engine verkleinert die Stichprobe, statt als Abwesenheit aufzutauchen.
  • position einer bewerteten Antwort ist der Zeichen-Offset des ersten Treffers Ihrer Marke: ein Näherungswert für Prominenz, kein Rang. Sie ist null, wenn die Marke fehlt.

Zurückgehaltene Veränderungen

changes, das mentionRateChangePp jeder Zelle sowie previousMentionRate und previousShareOfVoice jeder Marke sind null, und quality.comparable ist false, wenn sich die beiden Fenster nicht vergleichen lassen. quality.comparisonReason nennt den Grund: Jede Antwort behält die Definition, mit der sie bewertet wurde, und quality.scoringVersions listet die unterschiedlichen Definitionen über beide Fenster (legacy für Antworten ohne eine). Änderungen an Aliasen oder Wettbewerbern schreiben vergangene Antworten nie um. Einzige Ausnahme ist die wöchentliche Wettbewerber-Auswertung: Ändern sich die gefundenen Wettbewerber, werden die gespeicherten Antworten des Monitors gegen die neue Liste erneut bewertet.

Qualität

Laufzustand

health hat completed, failed, pending und topError (den häufigsten Fehlercode unter fehlgeschlagenen Tasks) für die Tasks des Monitors, die laufen oder in den letzten 24 Stunden abgeschlossen wurden. healthScope ist immer recent_visible_tasks. Es dient der Diagnose von Läufen, ist unabhängig vom Fenster und nie Teil des Nenners einer Quote.

Während eines Laufs abfragen

Jeder Aufruf liefert den vollständigen Bericht für Fenster und Filter. Während ein Lauf läuft, zählt health.pending seine noch laufenden Tasks. Lesen Sie den Bericht erneut, sobald der Wert 0 erreicht.

Kategorie-Berichte

Ein Kategorie-Monitor liefert vom selben Endpunkt einen anderen Body, mit denselben window, filters, quality, pauses und health:
  • stats und previous enthalten runs, named (Antworten, die mindestens eine verfolgte Marke nannten) und namedRate. changes.namedRatePp ist die Veränderung in Punkten.
  • category enthält das Ranking:
Zum Beispiel ein Eintrag in category.brands:
  • rank ordnet Marken nach der Zahl der Antworten, die sie nennen. Eine Marke, die keine Antwort genannt hat, hat rank: null.
  • mentionRate teilt durch die eigene sampleSize der Marke: die Antworten, die bewertet wurden, während sie auf der Liste stand.
  • shareOfVoice ist 100 × Nennungen dieser Marke / alle Markennennungen im Fenster, die Anteile ergeben also zusammen 100.

Fehler und Limits

  • Das Fenster beträgt höchstens 90 Tage.
  • Ungültige Parameter liefern 400 VALIDATION_ERROR mit einer Meldung, die das Problem nennt: days zusammen mit since oder until, nur eines von since und until, ein Zeitstempel ohne Zeitzone, eine Spanne über 90 Tage, ein until in der Zukunft, eine Engine, die nicht überwacht werden kann, ein Prompt über 2.000 Zeichen oder ein wiederholter Parameter.
  • Ein Bericht, der zu groß zum Aggregieren ist, liefert 400 VALIDATION_ERROR mit „This report is too large“. Schränken Sie Fenster, Engine oder Prompt ein.
Die Codes, die alle Monitor-Endpunkte teilen, stehen unter Monitore.

Nächste Schritte

Quellen und Antworten

Die zitierten Seiten und die Antworten hinter jeder Zahl.

Ereignisse und Alarme

Benachrichtigt werden, wenn sich Antworten ändern.