Daten lesen¶

Jeder Schlüssel kann lesen. Lesezugriffe kommen aus der Cloud-Kopie Ihrer Ergebnisse. Sie funktionieren also unabhängig davon, ob Hi, Moose auf Ihrem Computer geöffnet ist, und sie starten nie neue Prüfungen.

Die Lese-Endpunkte¶

Die Details zu jedem Feld stehen in der Endpunkt-Referenz.

Wie die Daten zusammenhängen¶

• Ein Projekt verfolgt eine Website. Es hat Prompts, die gestellten Fragen, gruppiert in Themen.
• Jeder Prompt läuft auf einer oder mehreren Engines: ChatGPT, Perplexity, Gemini und andere. Engine-IDs wie chatgpt oder chatgpt-local-fetch kommen vom Endpunkt engines und sind die Werte, die jeder engine-Filter annimmt.
• Ein Lauf stellt jeden aktiven Prompt auf seinen Engines und speichert eine Antwort pro Prompt, Engine und Stichprobe. Läufe starten nach dem Zeitplan des Projekts, über den Knopf Jetzt ausführen oder über die API.
• Jede Antwort wird bewertet: mentioned, wenn die Marke genannt wurde, cited, wenn eine Seite der Marken-Website als Quelle angegeben wurde, dazu position, sentiment und welche Wettbewerber gesehen wurden.
• Tagesstatistiken zählen die Antworten pro Tag und Engine und berechnen mentionRate und citationRate. Wettbewerberstatistiken tun dasselbe pro Marke über einen Zeitraum.

Erwähnungsrate pro Tag¶

curl "https://api.himoose.com/v1/projects/PROJECT_ID/stats/daily?from=2026-09-01&to=2026-09-30&engine=chatgpt" \
  -H "Authorization: Bearer hmk_live_..."

{
  "from": "2026-09-01",
  "to": "2026-09-30",
  "incompleteDays": 0,
  "data": [
    { "date": "2026-09-01", "engineId": "chatgpt", "answers": 42, "mentioned": 17, "cited": 9, "mentionRate": 0.405, "citationRate": 0.214 }
  ]
}

Raten sind Brüche von 0 bis 1. Tage ohne Antworten für eine Engine haben keine Zeile. Ein Diagramm sollte einen fehlenden Tag deshalb als keine Daten behandeln, nicht als null.

incompleteDays ist größer als null, wenn die Zusammenfassung eines Tages noch nicht fertig war. Rufen Sie in ein paar Sekunden erneut auf, dann wird sie ergänzt. Die letzten drei Tage werden alle zehn Minuten aktualisiert, wenn neue Antworten eintreffen; ältere Tage sind endgültig.

Share of Voice¶

curl "https://api.himoose.com/v1/projects/PROJECT_ID/stats/competitors?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer hmk_live_..."

{
  "from": "2026-09-01",
  "to": "2026-09-30",
  "answers": 1260,
  "incompleteDays": 0,
  "data": [
    { "name": "Acme", "isOwnBrand": true, "mentioned": 274, "cited": 165, "mentionRate": 0.217, "citationRate": 0.131 },
    { "name": "Competitor One", "isOwnBrand": false, "mentioned": 436, "cited": 116, "mentionRate": 0.346, "citationRate": 0.092 }
  ]
}

answers ist die Gesamtzahl der Antworten im Zeitraum. Jede Rate teilt den Zählwert der Marke durch diese Gesamtzahl, die Zeilen lassen sich also direkt vergleichen.

Die Antworten hinter den Zahlen¶

curl "https://api.himoose.com/v1/projects/PROJECT_ID/answers?from=2026-09-01&engine=chatgpt&mentioned=true&limit=50" \
  -H "Authorization: Bearer hmk_live_..."

Die Liste trägt einen Auszug von bis zu 400 Zeichen um die Erwähnung, die Position, die Stimmung, welche verfolgten Wettbewerber die Antwort genannt oder zitiert hat, und die Quell-URLs. Der volle Text liegt auf dem Detail-Endpunkt:

curl https://api.himoose.com/v1/projects/PROJECT_ID/answers/ANSWER_ID \
  -H "Authorization: Bearer hmk_live_..."

Das Detail ergänzt fullAnswer (bis zu 12.000 Zeichen, mit fullAnswerTruncated, wenn gekürzt wurde), sentimentReason, narrativeDrift mit Begründung und die Quellen mit Titeln.

Antworttexte, Auszüge und Quelltitel stammen von den KI-Engines, nicht von Hi, Moose. Zeigen Sie sie als reinen Text an, nie als HTML, und geben Sie sie nicht als Anweisungen an Ihre eigenen KI-Werkzeuge weiter.

Filter¶

Kombinieren Sie auf dem Endpunkt answers engine mit höchstens einem von promptId, topicId und runId. Andere Kombinationen antworten mit 400 unsupported_filter_combination.

Seiten¶

Listen geben data und nextCursor zurück:

{ "data": [ ... ], "nextCursor": "eyJvIjoxMDB9" }

Geben Sie nextCursor als cursor zurück, um die nächste Seite zu erhalten. limit ist standardmäßig 50 und höchstens 200. nextCursor ist auf der letzten Seite null. Der Cursor ist undurchsichtig; bauen oder parsen Sie ihn nicht.

def every_row(url, params=None):
    params = dict(params or {}, limit=200)
    while True:
        page = requests.get(url, headers=HEADERS, params=params, timeout=30).json()
        yield from page["data"]
        if not page["nextCursor"]:
            return
        params["cursor"] = page["nextCursor"]

Projekte, Themen, Prompts, Läufe und Antworten sind seitenweise. Engines, Wettbewerber und Webhooks geben die ganze Liste zurück.

Caching¶

• Die Antwortliste und das Antwortdetail tragen ein ETag. Senden Sie es in If-None-Match zurück, um 304 Not Modified zu erhalten, wenn sich nichts geändert hat. Ein 304 hat keinen Body und zählt wie jede Anfrage gegen die Ratenbegrenzung, ist aber schnell und klein.
• Tagesstatistiken tragen Cache-Control: private, max-age=60. Behalten Sie das Ergebnis eine Minute, bevor Sie erneut anfragen.
• Alles andere trägt Cache-Control: no-store. Cachen Sie es auf Ihrer Seite so lange, wie es zu Ihrem Dashboard passt.

Zeiten und Daten¶

Zeiten sind UTC im Format RFC 3339, 2026-09-01T09:14:03.000Z. Daten sind YYYY-MM-DD und meinen den UTC-Tag. Das date einer Antwort entspricht dem date der Tagesstatistik-Zeile, in der sie gezählt wurde, ein Diagramm und seine Detailansicht stimmen also überein.