Zugriff und Limits
Beide Endpoints erweitern die bestehende/public/v1-API. Sende deinen API-Schlüssel im Header cx-api-key. Der Schlüssel braucht analytics:read und muss einem Support-Agenten zugewiesen sein. Richte ihn unter Einstellungen → API ein.
Berichtsabfragen beachten die Dashboard-Berechtigungen sowie Kanal-, Team- und Agenten-Einschränkungen dieses Agenten. Eine Metrik im Katalog gibt dir nicht automatisch Zugriff auf ihre Daten.
Keiner der Endpoints verändert Tickets oder sendet Nachrichten. Unter Rate Limits findest du Hinweise zu Wiederholungen. Die OpenAPI-Referenz enthält die vollständigen Antwortschemas.
Für einzelne Umfragen und erfasste Login-Intervalle statt aggregierter Werte nutze CSAT- und Sitzungsexporte. Diese Endpoints erfordern organisationsweiten Dashboard-Zugriff.
Metriken entdecken
{ "success": true, "data": [...] }. Sie enthält den vollständigen statischen Katalog ohne Pagination. Jeder Eintrag hat folgende Felder:
Der Katalog enthält keine Tickets, Kundendaten, Workspace-Entitäts-IDs oder internen Datenquellennamen. Namen und Beschreibungen sind auf Englisch. Cache diese Metadaten, statt sie vor jeder Abfrage neu zu laden. Nicht jede Metrik unterstützt jede Gruppierung oder Visualisierung.
Berichtsdaten abfragen
Starte mit einer Metrik und einem kurzen Zeitraum. Sende JSON mit zwei Pflichtfeldern:query und einer IANA-Zeitzone in timezone, zum Beispiel Europe/Vienna oder UTC. Für die Rohdaten-Pagination kannst du zusätzlich das unten beschriebene optionale Feld cursor senden.
{ "success": true, "data": ... }. Über data.kind erkennst du die Ergebnisform: kpi enthält zum Beispiel value, previousValue und format; time-series enthält series und points. Du erhältst Diagrammdaten, kein Bild und keinen CSV-Export.
Abfragesprache
Schreibe jede Klausel in eine eigene Zeile. Das ist die CX-Berichtsabfragesprache, kein SQL: Beliebige Tabellen, Joins und SQL-Ausdrücke sind nicht erlaubt. Für Public API v1 gelten die kanonischen Formen auf dieser Seite:WHERE, metrikfreies VISUALIZE TYPE und typisierte SET-Zeilen. Der Service kann einige ältere gespeicherte Aliasformen weiterhin lesen. Neue Clients dürfen jedoch weder FILTER noch OPTIONS oder Metriklisten in VISUALIZE erzeugen.
Die Public API v1 unterstützt
kpi, line, area, grouped_bar, stacked_bar, split_bar, horizontal_bar, data_table und agent_table. Diagramme brauchen Metriken mit demselben format; stapel keine unterschiedlichen Einheiten oder nicht addierbaren Reihen. Eine data_table darf Formate mischen und unterstützt bis zu zwei Kategoriegruppen plus eine optionale Zeitgruppe. Die coordinates jeder Zeile halten die Dimensionen getrennt fest. Alle Metriken, auch Automatisierung und CSAT, nutzen FROM tickets; es gibt keine separaten Nachrichten- oder Umfragedatensätze. Pivot-Tabellen und Heatmaps gehören nicht zum öffentlichen v1-Vertrag.
Rohe Ticketfelder
Nutze den Rohdatenmodus, wenn du eine Zeile pro Ticket statt aggregierter Metriken brauchst. ErsetzeSHOW und VISUALIZE durch ein erlaubtes SELECT und FORMAT raw:
FROM tickets, SELECT, einen Zeitraum, LIMIT und FORMAT raw. Kombiniere ihn nicht mit SHOW, WHERE, GROUP BY, TIMESERIES, COMPARE TO, ORDER BY, SET oder VISUALIZE. DURING und SINCE ... UNTIL ... filtern nach dem Erstellungszeitpunkt des Tickets. Das unterscheidet sich von aggregierten Metriken, die das Ereignis aus ihrer jeweiligen Zuordnung nutzen.
Du kannst bis zu 100 Zeilen pro Request auswählen. Ergebnisse sind absteigend nach created_at und danach nach ticket_id sortiert. Wenn data.pagination.has_more den Wert true hat, sende data.pagination.next_cursor im nächsten Request als oberstes Feld cursor neben query und timezone. Ein Cursor ist an den API-Agenten und die exakte Abfrage gebunden.
Rohe Zeilen schließen gelöschte, importierte und Seitentickets aus. Dashboard-Berechtigungen sowie Kanal-, Team- und Agenten-Einschränkungen gelten weiterhin. Der Rohdatenmodus enthält bewusst keine Kundeninhalte und keinen vollständigen Statusverlauf. Für eigene Kategoriefelder wie „Kontaktgrund“ nutze die Ticketfeld-Erweiterung; der Rohdatenmodus rät nicht, welches benutzerdefinierte Feld deine Kategorie darstellt.
Gruppieren und filtern
GROUP BY verändert die Form des Ergebnisses; WHERE entfernt Tickets vor der Aggregation. GROUP BY channel_type liefert zum Beispiel eine Zeile oder Serie je Kanaltyp. WHERE channel_type IN ("email", "whatsapp") berücksichtigt dagegen nur E-Mail- und WhatsApp-Datensätze. channel_type steht für allgemeine Transportarten, connected_channel für eingerichtete Kanalverbindungen. Mit topic_l2 und topic_l3 wählst du unterschiedliche Ebenen der Themenhierarchie.
Mit TIMESERIES oder einer Zeit-ID in GROUP BY legst du hour, day, week oder month fest. LIMIT begrenzt zurückgegebene Kategoriezeilen. Es senkt weder die Abfragekosten noch verändert es Nenner von Prozentmetriken oder berechnet Gesamtsummen neu.
Abfragebeispiele
Sende jede vollständige Abfrage unten alsquery-String im HTTP-Request oben, mit timezone: "Europe/Vienna". Datumsangaben und Metrik-IDs behalten in allen Beispielen dasselbe Format.
Tägliches Ticketvolumen
Vergleiche erstellte und gelöste Tickets je Tag. Das sind unterschiedliche Ereignisgruppen, nicht unbedingt dieselben Tickets.Ticket-KPI für gestern
Vergleiche neue Anfragen mit dem Vortag.Neue Tickets nach Kanal
Sortiere Kanaltypen nach eingehendem Ticketvolumen.channel_type liefert Transportarten wie email und whatsapp; mit connected_channel gruppierst du nach einzelnen verbundenen Postfächern.
Tickets nach Kontaktgrund
Vergleiche neue und gelöste Tickets für ausgewählte Kontaktgründe. Dieses Beispiel setzt ein Dropdown-Ticketfeld mit dem gespeichertenfield_key contact_reason, dem Anzeigenamen Contact reason und den Optionsnamen Delivery und Return voraus. Ersetze sie durch den Feldschlüssel und die Optionsnamen deines Workspaces.
GROUP BY ticket_field("contact_reason") wählt direkt ein bestimmtes Feld. Alternativ akzeptiert SET ticket_field den gespeicherten Feldschlüssel (contact_reason) oder den Anzeigenamen (Contact reason). Leerzeichen am Anfang und Ende sowie Groß-/Kleinschreibung werden beim Abgleich ignoriert. Nutze den gespeicherten field_key aus der öffentlichen Ticketfeld-Erweiterung: Fordere include=ticket_fields bei GET /public/v1/tickets oder GET /public/v1/tickets/:ticketNumber an. Leite keinen Schlüssel aus dem Namen ab, indem du Leer- oder Satzzeichen ersetzt. Ein Name kann sich ändern, ohne dass sich der gespeicherte Schlüssel ändert. Wenn du den Feldschlüssel selbst änderst, passe auch die Abfragen deiner Integration an.
SET ticket_field_values wählt Optionsnamen innerhalb dieses Felds aus. Dabei gelten dieselben Regeln für Leerzeichen und Groß-/Kleinschreibung. Lasse die Option weg, um alle Werte des ausgewählten Felds einzubeziehen. Der exakte Wert "all" ist für alle Felder oder alle Werte reserviert. Für einzelne Werte musst du ein Feld statt "all" auswählen.
Passt eine Referenz zu mehr als einer Entität, lehnt die API sie mit 400 VALIDATION_ERROR ab. Das gilt auch, wenn der Name eines Felds dem Schlüssel eines anderen entspricht. Die kanonische v1-Sprache akzeptiert über SET ticket_field einen Feldschlüssel oder Anzeigenamen. Interne Kompatibilitätsoptionen mit IDs gehören nicht zum dokumentierten v1-Vertrag.
Diese Einstellungen begrenzen die Kategorieaufteilung, nicht die Ticketmenge eines eigenständigen KPIs. Sie ermöglichen keine WHERE-Filter mit benutzerdefinierten Feldschlüsseln oder Optionsnamen.
Kontaktgründe in Prozent und fehlende Werte
Zeige Anzahl und Prozentwerte zusammen.new_tickets_share teilt die eindeutigen neuen Tickets je Kategorie durch alle zulässigen neuen Tickets mit passendem Zeitraum, Berechtigungen und WHERE-Filtern. Der Nenner wird vor Feld-/Optionsauswahl, Gruppierung, topN oder LIMIT berechnet. Zum Beispiel bleiben 20 Delivery-Tickets von 100 passenden Tickets bei 20 %, auch wenn du nur Delivery auswählst oder das Ergebnis auf eine Zeile begrenzt.
SET include_missing ist ein Boolean und standardmäßig deaktiviert. Bei aktiven, nicht archivierten Ticketfeldern ergänzt true eine Kategorie Missing für Tickets ohne nutzbaren Wert, auch bei leerem Text. Boolean false und die Zahl 0 sind Werte, nicht fehlend. Fehlende Tickets bleiben auch bei ausgewählten Optionsnamen berücksichtigt; ein anderer ausgefüllter Optionswert wird nicht als fehlend umgedeutet. Bei allen Feldern wird die fehlende Belegung pro Feld berechnet. Limits können diese Zeile trotzdem ausblenden. Prozentwerte über mehrere Felder oder überlappende Werte müssen nicht 100 % ergeben; ein Zeilenlimit berechnet sie nicht neu.
Aktive Ticketbearbeitungszeit
average_ticket_handle_time misst Ticketbearbeitungszeit nur, wenn dieselbe Person während der Bearbeitungsphase eine relevante, gespeicherte Aktion an diesem Ticket ausführt. Dazu zählen Änderungen am Ticket oder an der Zuweisung, Notizen sowie das Bearbeiten, Löschen oder Ausblenden einer Nachricht. Eine Antwort oder E-Mail zählt erst, wenn die verknüpfte Nachricht den Status sent, delivered oder read hat; wartende oder fehlgeschlagene Nachrichten zählen nicht. Öffnen, Lesen, Tippen oder Klicken allein reicht nicht aus.
Pro Person und Workspace läuft über alle Tabs hinweg nur ein Ticket-Timer. Beim Ticketwechsel läuft der Timer für das neue Ticket weiter. Der Wechsel in einen externen Tab pausiert ihn nicht. Nach 30 Minuten ohne Aktivität stoppt der Timer; die nächste Aktivität beginnt eine neue Bearbeitungsphase. Eine Aktion aus einer früheren Phase qualifiziert keine spätere. Kehrst du innerhalb derselben Phase zu einem Ticket zurück, werden die Zeiten addiert: 10 Minuten auf A, 20 auf B und weitere 30 auf A ergeben 40 Minuten für A und 20 für B, sofern jedes Ticket eine qualifizierende Aktion hat. Eine spätere Aktion auf A kann alle 40 Minuten qualifizieren.
Berichte enthalten auch laufende, noch nicht gespeicherte Zeit – höchstens bis jetzt oder bis zur 30-Minuten-Inaktivitätsgrenze, je nachdem, was früher liegt. Wird eine qualifizierende Aktion verspätet gespeichert, erscheint sie beim nächsten Abruf. Gelöschte, importierte und Seitentickets sind ausgeschlossen.
Der gesamte Sitzungswert zählt im Zeitraum und Zeitabschnitt der effektiven letzten Beobachtung oder des Endes (ended_at, gegebenenfalls um den laufenden Timer verlängert). Er wird durch die Anzahl eindeutiger Agent-Ticket-Paare in diesem Abschnitt geteilt. Sitzungen über Mitternacht oder eine Berichtsgrenze werden nicht minutengenau aufgeteilt: Eine am Dienstag endende Sitzung zählt vollständig zum Dienstag, auch wenn sie am Montag begann. Eine spätere Beobachtung kann den gesamten Wert in einen späteren Abschnitt verschieben. Das Ende des Berichtszeitraums ist exklusiv. Fehlende historische Erfassung wird nicht durch Lösungs- oder Online-Zeiten ersetzt.
Frage AHT nach menschlichem Agenten ab, um gemessene Ticketarbeit zu vergleichen. Werte werden in Sekunden geliefert. human_agent ist der Agent, dem die gemessene Arbeit zugeordnet wurde, nicht zwingend der aktuell zugewiesene oder erfasste Lösungsagent.
Zeiten bis zur ersten Antwort
Vergleiche die mediane Wartezeit auf eine qualifizierende menschliche oder KI-Antwort mit der Wartezeit auf eine menschliche Antwort. Beide Reihen liefern Sekunden, keine Durchschnittswerte.responseTimeAttribution weg und behält das bisherige Datums- und Werteverhalten der FRT bei. Das bisherige Datum ist die Ticketerstellung plus die ausgewählten gespeicherten FRT-Sekunden, kein erfasster Antwortzeitpunkt. Ohne diese Option nutzt auch human_first_response_time_mean dieselbe bisherige Grundgesamtheit wie human_first_response_time, selbst wenn erfasste Zeitstempel vorhanden sind. Menschliche FRT misst Wartezeit innerhalb der Geschäftszeiten. Sie zur Erstellung zu addieren ergibt deshalb nicht den tatsächlichen Antwortzeitpunkt.
Mittelwert und Median der ersten menschlichen Antwort
Mit dem Mittelwert erkennst du den Einfluss besonders langer Wartezeiten, mit dem Median eine typische Wartezeit. Beide nutzen dieselben zulässigen menschlichen Antwortbeobachtungen und liefern numerische Sekunden, keine formatierten Zeitstrings. Bei 60, 120 und 900 Sekunden beträgt der Mittelwert 360 Sekunden und der Median 120 Sekunden. Dieses Beispiel aktiviert ausdrücklich erfasste Antwortzeitpunkte statt der bisherigen Datumsberechnung:SET response_time_attribution = recorded_reply stellt alle ausgewählten FRT-Metriken (customer_first_response_time, human_first_response_time, human_first_response_time_mean und ai_first_response_time) auf ihre gespeicherten tatsächlichen Antwortzeitpunkte um. Für die Kunden-FRT wählt die Option die früheste qualifizierende gespeicherte menschliche oder KI-Antwort samt zugehöriger Dauer, wobei Zeitpunkt und Dauer vorhanden sein müssen, statt menschliche Geschäftszeitsekunden mit verstrichenen KI-Sekunden zu vergleichen. Andere Metriken einer gemischten Tabelle behalten ihre eigene Zuordnung. Die Option braucht mindestens eine FRT-Metrik und wird von agent_table nicht unterstützt. Jeder andere Wert, auch "legacy", oder die Verwendung ohne FRT-Metrik liefert 400 VALIDATION_ERROR. Für bisheriges Verhalten lässt du die Option weg.
CSAT-Wert und Stichprobengröße
Zeige die Anzahl der Antworten neben dem Wert, damit du kleine Stichproben einschätzen kannst. Eine Tabelle erlaubt Dezimalwert und Anzahl in einem Ergebnis.CSAT-Antwortquote nach Versandkohorte und Agent
Vergleiche versendete Umfragen, davon eingereichte und bewertete Umfragen sowie ihre Antwortquote. Bei gleichem Umfang giltcsat_response_rate = 100 × csat_answered_from_sent / csat_sent. Spätere Einreichungen aktualisieren die ursprüngliche Versandkohorte, auch nach Ende des Berichtszeitraums. Teile nicht csat_responses durch csat_sent: Erstere zählt nach Einreichungsdatum und kann früher versendete Umfragen enthalten. Ohne versendete Umfragen ist die Quote null.
Antworten und Online-Zeit pro Stunde
Vergleiche öffentliche menschliche Nachrichten mit Online-Sekunden je Agent und Stunde. Das sind unterschiedliche Grundgesamtheiten: Eine Person kann online sein, ohne zu antworten. Die Zeilen vereinen alle beobachteten Zeit-/Agentenpaare der ausgewählten Metriken. Fehlende Metrikzellen darin sind null; es entsteht kein vollständiges Raster aller Agenten und Stunden.Wöchentlich gelöste Tickets je Agent
Prüfe den Lösungsdurchsatz nach erfasstem Lösungsagenten und Woche, nicht die in dieser Woche erstellten Tickets.Monatliche Agentenaktivität
Setze den Agenten an die erste Stelle der Zeilendimensionen, um monatliche Antworten und Online-Zeit zu prüfen. Die umgekehrte Dimensionsreihenfolge ändert die Darstellung, nicht die ausgewählten Grundgesamtheiten.Einsparungen und KI-Ausgaben
Vergleiche geschätzte Einsparungen mit geschätzten Ausgaben in EUR. Dieses Tagesdiagramm nutzt dasselbe Format für beide Reihen und ist kein Rechnungsabgleich. Diese speziellen Automatisierungsmetriken unterstützen KPIs, tägliche Diagramme oder Tabellen sowie Aktionsaufteilungen, außer bei KI-Ausgaben. Mische sie nicht mit anderen Ticketmetriken und ergänze keine Kategorieaufteilungen.Gefilterte Teamauslastung
Prüfe gelöste deutschsprachige Tickets nach Team, einschließlich Lösungsdauer. Mehrere Filter werden mit AND verknüpft.status ist der aktuelle Ticketstatus, nicht der Status bei Erstellung. Nutze für Filter wie team, channel_type, connected_channel oder human_agent die Entitäts-IDs deines Workspaces statt Anzeigenamen.
Aktuell auf Kunden wartende Tickets
Zähle offene Tickets, die auf Informationen vom Kunden warten, nicht Kunden, die auf den Support warten. Die Sprache verlangt eine Datumsklausel, aber diese macht einen Snapshot nicht zu historischen Daten. Ergänze bei Snapshots wederTIMESERIES noch COMPARE TO.
Ergebnisse lesen
Diese Antwortformen nutzen erfundene Beispielwerte, keine garantierten Ergebnisse für die Beispielzeiträume. Zeilen und Datenpunkte sind gekürzt. Nutze zurückgegebene Labels und Schlüssel, statt übersetzte Labels oder feste Kanal-IDs anzunehmen. Ein KPI liefert eine Zahl und ihr Format.previousValue kann null sein; historische KPIs können auch ohne expliziten Vergleich einen Vorperiodenwert enthalten. Mit COMPARE TO wählst du den Vergleichszeitraum ausdrücklich. Snapshot-KPIs haben keinen historischen Vergleich.
series. Explizite Vergleiche ergänzen Reihenschlüssel mit der Endung __compare.
rowDimension die erste angefragte Dimension. Das zusätzliche Array rowDimensions listet beide Dimensionen in Request-Reihenfolge. Jede Zeile ergänzt eine dimensions-Map mit getrennten Schlüsseln und Labels. Behandle den kombinierten Zeilenschlüssel key als undurchsichtige Kennung. Tabellen mit einer Dimension behalten ihre bisherige Form; Clients müssen die neuen optionalen Felder tolerieren. Die optionale average-Zeile ist eine Anzeigezusammenfassung, keine neu berechnete Periodenmetrik. Mit SET show_average_row = false lässt du sie weg. coordinates ist der kanonische Ort für Tabellenkoordinaten; dimensions bleibt für bestehende Clients als Kompatibilitätsfeld erhalten.
Metrikreferenz
Unten stehen alle 58 registrierten Metrik-IDs, gruppiert wie im Katalog. Aggregation, Format und Zuordnung sind die exakten Katalogwerte. Du wählst die Metrik, keine eigene Aggregationsfunktion.countzählt die definierten Tickets, Nachrichten, Umfragen, Aktionen oder Ereignisse;sumaddiert Werte;averageist das arithmetische Mittel;medianist der mittlere Beobachtungswert;ratioteilt den passenden Zähler durch seinen Nenner.duration-secondsliefert Sekunden,currency-eurEUR,decimaleinen Dezimalwert undpercentProzentwerte:75bedeutet 75 %, nicht0.75. CSAT-Werte nutzen eine Skala von 1 bis 5.- Die Zuordnung bestimmt den Datumsbezug:
ticket_createdist eine Erstellungskohorte;ticket_resolved,reply_event,reopen_event,reassignment_event,survey_submitted,action_executedundorder_paidbeziehen sich auf das jeweilige Ereignis.agent_presencemisst Online-Sitzungszeit;mixed_eventskombiniert Erstellung und Lösung;current_snapshotbedeutet jetzt. - Werte einer Erstellungskohorte können sich mit den Tickets weiterentwickeln. Besonders
messagesundmessages_per_ticketenthalten erfasste Nachrichten auf Tickets, die im Zeitraum erstellt wurden, nicht nur Nachrichten, die darin gesendet wurden. Für öffentliche menschliche Nachrichten mit Sendedatum im Zeitraum nutzeagent_messages. - Aktuelle Snapshots erlauben keine Zeitdimensionen oder historischen Vergleiche. Das Alter offener Tickets zählt ab Erstellung, nicht ab der letzten Nachricht. Auch mit einer älteren Datumsklausel rekonstruiert ein Snapshot keinen Rückstand zum Periodenende.
- Raten nutzen die Nenner in den Definitionen unten, innerhalb des jeweiligen Umfangs. Nullwerte oder leere Ergebnisse beweisen allein keine fehlende Aktivität: Berichtsdaten können unvollständig sein oder auf Aktualisierung warten. Prüfe wichtige Summen, bevor du sie für Zusagen oder Finanzberichte nutzt.
csat_sentundcsat_answered_from_sentnutzensurvey_sentals Zuordnung. Auchcsat_response_ratenutzt die Versandkohorte, behält aber die bestehende Katalogzuordnungsurvey_submitted. Bewertungs- und Einreichungsmetriken nutzen das Einreichungsdatum.time_savedundmoney_savedsind Schätzungen aus den Aktionszeiten und dem Stundensatz deines Workspaces.ai_spendrechnet erfasste KI-Credits mit einem EUR-pro-Credit-Ersatzwert um; das ist weder deine Rechnung noch eine Garantie deines Vertragspreises. Obwohl im Katalogaction_executedsteht, zählt für Ausgaben das Erstellungsdatum des KI-Laufs, auch an Tagen ohne erfasste Aktionen.
Volumen und Auslastung
Antwort und Lösung
Qualität und Zufriedenheit
KI und Automatisierung
Fehlerbehebung
Zeitraumvalidierung, eine geschätzte Aufwandsprüfung und Limits für zurückgegebene Zeilen oder Punkte garantieren weder eine allgemeine maximale Laufzeit noch eine Grenze für jede Ergebniszelle oder zugrunde liegende Datenbankoperation.
LIMIT kürzt zurückgegebene Zeilen oder Punkte; es ist keine Pagination und garantiert nicht weniger Datenbankarbeit. Teile große Reporting-Aufgaben in kleinere Zeitfenster. Historische Vollständigkeit und Aktualität hängen von den verfügbaren Berichtsdaten ab; eine erfolgreiche Antwort bestätigt beides nicht. Scheitert eine gültige kleine Abfrage oder wirken Summen unvollständig, kontaktiere den Support mit der request_id aus der Antwort, der Zeitzone und einer bereinigten Abfrage. Teile niemals deinen API-Schlüssel.