# Analytics

Über die Analytics-Endpunkte fragen Sie die Konversationsdaten Ihres Chatbots ab: Sie suchen Konversationen nach Zeitraum und weiteren Kriterien und rufen alle Events einer einzelnen Konversation ab. Damit können Sie z. B. Konversationen in eigene Auswertungs- oder BI-Systeme übernehmen oder gezielt Konversationen mit negativem Feedback oder Weiß-nicht-Antworten weiterverarbeiten.

Voraussetzungen für alle Anfragen (Basis-URL, Authorization- und kauz-chatbot-Header) finden Sie im Überblick .

Methode	Pfad	Beschreibung
`POST`	`/partner/v1/conversations/search`	Sucht Konversationen anhand von Filtern.
`GET`	`/partner/v1/events/by-conversation/{conversationId}`	Liefert alle Events einer Konversation.

# POST `/partner/v1/conversations/search`

Sucht die Konversationen des Chatbots, die im angegebenen Zeitraum begonnen haben. Alle weiteren Filter sind optional und werden miteinander kombiniert (UND-Verknüpfung). Lassen Sie einen Filter weg, wird nicht danach gefiltert.

# Anfrage

Feld	Typ	Pflicht	Beschreibung
`fromDate`	string	ja	Konversationen, die zu oder nach diesem Zeitpunkt begonnen haben (ISO 8601).
`toDate`	string	ja	Konversationen, die zu oder vor diesem Zeitpunkt begonnen haben (ISO 8601).
`referrers`	array<string>	nein	Nur Konversationen, deren Referrer mit einem dieser Werte beginnt, z. B. `https://example.com/hilfe`.
`plainText`	string	nein	Nur Konversationen mit einer Nachricht, die diese Phrase enthält.
`includeEmptyConversations`	boolean	nein	Ob leere Konversationen enthalten sind, siehe Leere Konversationen . Standardwert `true`.
`userFeedbackForConversation`	array<string>	nein	Nur Konversationen, die dieder Nutzerin mit einem dieser Werte bewertet hat: `positive`, `negative`. Ein leeres Array trifft auf keine Konversation zu.
`userFeedbackForAnswer`	array<string>	nein	Nur Konversationen mit mindestens einer Antwort, die dieder Nutzerin mit einem dieser Werte bewertet hat: `positive`, `negative`. Ein leeres Array trifft auf keine Konversation zu.
`onlyWithDontKnowAnswers`	boolean	nein	`true` liefert nur Konversationen, in denen der Chatbot mindestens eine Frage nicht beantworten konnte (Weiß-nicht-Antwort). Standardwert `false`, also keine Einschränkung.
`semanticLabelIdsPerCategory`	array<array<string>>	nein	Filter nach Labels, siehe Nach Labels filtern .
`cursor`	array	nein	`nextCursor` bzw. `previousCursor` aus einer vorherigen Antwort, unverändert. Für die erste Seite weglassen. Siehe Blättern .
`direction`	string	nein	`next` (ältere Konversationen) oder `previous` (neuere Konversationen). Erfordert `cursor`.

# Leere Konversationen

Beim Öffnen des Kauz-Chatfensters entsteht eine Konversation mit zwei Events: dem Trigger für die Begrüßung (CR:firstGreeting) und der Begrüßung selbst. Findet danach keine Interaktion statt, bleibt eine solche quasi leere Konversation in den Daten bestehen. Mit includeEmptyConversations: false schließen Sie Konversationen mit weniger als drei Events aus. Zusätzlich wird CR:firstGreeting dann nicht in eventCount und userInputCount mitgezählt.

Maßgeblich ist allein die Zahl der Events. Sendet Ihr eigenes Frontend keine Begrüßung, wird auch eine Konversation aus genau einer Frage und einer Antwort ausgeschlossen.

# Nach Labels filtern

Labels vergeben Sie im aiStudio über den Conversation-Labeler . Jedes innere Array steht für eine Label-Kategorie: Innerhalb eines Arrays werden die Label-IDs mit ODER verknüpft, zwischen den Arrays mit UND.

{
  "semanticLabelIdsPerCategory": [
    ["label-id-a", "label-id-b"],
    ["label-id-c"]
  ]
}

Dieses Beispiel liefert Konversationen, die mit label-id-a oder label-id-b und mit label-id-c gelabelt sind. Ein leeres äußeres Array ([]) filtert nicht, ein leeres inneres Array ([[]]) trifft auf keine Konversation zu.

Die Partner-API arbeitet ausschließlich mit Label-IDs. Welche IDs einer Konversation zugeordnet sind, sehen Sie in semanticLabelIds der Antwort.

# Antwort

Feld	Typ	Beschreibung
`conversations[]`	array	Konversationen dieser Seite, neueste zuerst, höchstens 50. Siehe Felder unten.
`totalFoundConversations`	number	Anzahl aller Treffer über alle Seiten. Fehlt, sobald `userFeedbackForConversation`, `userFeedbackForAnswer`, `plainText` oder `onlyWithDontKnowAnswers` gesetzt ist.
`nextCursor`	array	Cursor für die nächste (ältere) Seite. Fehlt auf der letzten Seite.
`previousCursor`	array	Cursor für die vorherige (neuere) Seite. Fehlt auf der ersten Seite.

Felder je Konversation:

Feld	Typ	Beschreibung
`id`	string	Eindeutige ID der Konversation.
`createdAt`	string	Beginn der Konversation (ISO 8601).
`referrers`	array<string>	Referrer, von denen aus die Konversation geführt wurde.
`deviceTypes`	array<string>	Gerätetypen derdes Nutzerin: `smartphone`, `tablet`, `desktop` oder `unknown`.
`eventCount`	number	Anzahl der Events: Nutzer*innen-Nachrichten, Bot-Nachrichten und Analytics-Events.
`userInputCount`	number	Anzahl der Nutzer*innen-Nachrichten.
`semanticLabelIds`	array<string>	IDs der Labels, die der Konversation zugeordnet sind.
`userRating`	string	Bewertung der Konversation durch dieden Nutzerin: `positive`, `negative` oder `neutral`. Fehlt, wenn die Konversation nicht bewertet wurde.
`userComment`	string	Kommentar, den dieder Nutzerin zur Bewertung abgegeben hat.

# Blättern

Die Suche liefert höchstens 50 Konversationen pro Seite, die neuesten zuerst. Geblättert wird über einen Cursor statt über limit und offset:

Senden Sie die erste Anfrage ohne cursor und direction.
Für die nächste, ältere Seite senden Sie dieselben Filter erneut, zusammen mit cursor = nextCursor der letzten Antwort und direction: "next".
Für die vorherige, neuere Seite senden Sie cursor = previousCursor und direction: "previous".

Übernehmen Sie den Cursor unverändert und lassen Sie die Filter zwischen den Seiten gleich. Fehlt nextCursor in der Antwort, ist die letzte Seite erreicht. Senden Sie direction ohne cursor, erhalten Sie den Fehler 400.

curl --location --request POST "https://example.kauz.ai/partner/v1/conversations/search" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
--data-raw "{
   \"fromDate\":\"2026-10-01T00:00:00.000Z\",
   \"toDate\":\"2026-10-31T23:59:59.999Z\",
   \"referrers\":[\"https://example.com/hilfe\"],
   \"includeEmptyConversations\":false
}"

{
  "conversations": [
    {
      "id": "a311a62f-8e01-445a-89e2-186ebf016d55",
      "createdAt": "2026-10-09T14:30:09.938Z",
      "referrers": ["https://example.com/hilfe"],
      "deviceTypes": ["desktop"],
      "eventCount": 6,
      "userInputCount": 2,
      "semanticLabelIds": ["0b6c1f2e-7d4a-4f0e-9c1a-3e5d7f9b2a11"],
      "userRating": "negative",
      "userComment": "Meine Frage wurde nicht beantwortet."
    }
  ],
  "totalFoundConversations": 154,
  "nextCursor": [1774882326648, "028d64dd-e5e4-4d17-8b6d-58f5c0a80e1e"]
}

curl --location --request POST "https://example.kauz.ai/partner/v1/conversations/search" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
--data-raw "{
   \"fromDate\":\"2026-10-01T00:00:00.000Z\",
   \"toDate\":\"2026-10-31T23:59:59.999Z\",
   \"referrers\":[\"https://example.com/hilfe\"],
   \"includeEmptyConversations\":false,
   \"cursor\":[1774882326648,\"028d64dd-e5e4-4d17-8b6d-58f5c0a80e1e\"],
   \"direction\":\"next\"
}"

# GET `/partner/v1/events/by-conversation/

Liefert die Events einer Konversation in zeitlicher Reihenfolge, die ältesten zuerst. Die conversationId erhalten Sie aus der Konversationssuche oder aus der Antwortgenerierung . Die eventId einer Bot-Nachricht entspricht der id der Antwort aus der Antwortgenerierung.

Für eine unbekannte conversationId antwortet der Endpunkt mit 200 und einer leeren Liste ({"events": []}), nicht mit 404.

# Antwort

Feld	Typ	Beschreibung
`events[]`	array	Events der Konversation, die ältesten zuerst. Siehe Felder unten.

Felder, die jedes Event enthält:

Feld	Typ	Beschreibung
`conversationId`	string	ID der Konversation.
`eventId`	string	Eindeutige ID des Events.
`type`	string	`Message` (Nachricht) oder `Analytics` (Interaktion).
`senderType`	string	`USER` oder `BOT`.
`date`	string	Zeitpunkt des Events (ISO 8601).

Je nach Event zusätzlich, sofern vorhanden:

Feld	Typ	Beschreibung
`referrer`	string	Referrer, von dem aus das Event gesendet wurde.
`deviceType`	string	`smartphone`, `tablet`, `desktop` oder `unknown`.
`content`	string	Text der Nachricht. Bot-Nachrichten enthalten Kauz-Markup .
`userCategory`	string	Nutzergruppe, z. B. gesetzt über das Tool Metadaten setzen .

Zusätzliche Felder bei Bot-Nachrichten:

Feld	Typ	Beschreibung
`answerType`	string	`GENERATED` (generierte Antwort), `PREDEFINED` (Antwort aus dem Themenkatalog) oder `SYSTEM` (Systemantwort).
`language`	string	Sprache der Antwort.
`userRating`	string	Bewertung der Antwort durch dieden Nutzerin: `positive` oder `negative`.
`editorialRating`	string	Bewertung der Antwort im aiStudio: `unrated`, `correct`, `acceptable`, `false` oder `missingInfo`.
`agent`	string	Name des Agenten, der die Antwort erzeugt hat.
`agentType`	string	Typ des Agenten, z. B. `rag` oder `data collection`.
`tools[]`	array	Vom Agenten genutzte Tools, jeweils mit `name`, `type` und `success` (boolean).
`searchMethod`	string	Suchmethode des RAG-Agenten: `keywordSearch`, `vectorSearch` oder `hybridSearch`.
`alphaValue`	number	Alpha-Wert der hybriden Suche.
`model`	string	Für die Antwortgenerierung genutztes Modell.
`modelSelection`	string	`automatic` oder `manual`.
`promptLength`	number	Länge des vollständigen Prompts in Zeichen.
`topicCatalogEntryIds`	array<string>	IDs der Themenkatalogeinträge, aus denen die Antwort stammt.

Zusätzliche Felder bei Analytics-Events:

Feld	Typ	Beschreibung
`action`	string	Ausgeführte Aktion: `openLink` oder `changeLanguage`.
`clickedLinks`	array<string>	Bei `openLink`: geöffnete Links.
`languageSwitchFrom`	string	Bei `changeLanguage`: Ausgangssprache.
`languageSwitchTo`	string	Bei `changeLanguage`: Zielsprache.

Als eigene Analytics-Events erscheinen nur Link-Klicks und Sprachwechsel. Die Bewertung einer Antwort steht als userRating an der bewerteten Bot-Nachricht. Andere Analytics-Events , z. B. kauz_livechat_offer, sind in der Liste nicht enthalten, werden in der Konversationssuche aber in eventCount mitgezählt.

curl --location "https://example.kauz.ai/partner/v1/events/by-conversation/a311a62f-8e01-445a-89e2-186ebf016d55" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk"

{
  "events": [
    {
      "conversationId": "a311a62f-8e01-445a-89e2-186ebf016d55",
      "eventId": "27bd97d3-6f96-47d2-a371-e9382c28c29c",
      "type": "Message",
      "senderType": "USER",
      "date": "2026-10-09T14:30:09.938Z",
      "referrer": "https://example.com/hilfe",
      "deviceType": "desktop",
      "content": "Wie lange dauert der Versand?"
    },
    {
      "conversationId": "a311a62f-8e01-445a-89e2-186ebf016d55",
      "eventId": "51a156da-9393-4a0a-af1e-e76d4d5dbfc7",
      "type": "Message",
      "senderType": "BOT",
      "date": "2026-10-09T14:30:12.534Z",
      "referrer": "https://example.com/hilfe",
      "deviceType": "desktop",
      "content": "Der Versand dauert 2–3 Werktage. <hyperlink destination=\"https://example.com/versand\">Mehr zum Versand</hyperlink>",
      "answerType": "GENERATED",
      "language": "DE",
      "userRating": "positive",
      "agent": "Standardagent",
      "agentType": "rag",
      "searchMethod": "hybridSearch",
      "alphaValue": 0.5,
      "model": "GPT-4.1 mini",
      "modelSelection": "automatic",
      "promptLength": 5168
    },
    {
      "conversationId": "a311a62f-8e01-445a-89e2-186ebf016d55",
      "eventId": "4098db68-17d9-4216-bf41-4a3e751637f4",
      "type": "Analytics",
      "senderType": "USER",
      "date": "2026-10-09T14:30:20.101Z",
      "referrer": "https://example.com/hilfe",
      "action": "openLink",
      "clickedLinks": ["https://example.com/versand"]
    }
  ]
}

# Analytics

# POST /partner/v1/conversations/search

# Anfrage

# Leere Konversationen

# Nach Labels filtern

# Antwort

# Blättern

# GET `/partner/v1/events/by-conversation/

# Antwort

# POST `/partner/v1/conversations/search`