> ## Documentation Index > Fetch the complete documentation index at: https://docs.armin.cx/llms.txt > Use this file to discover all available pages before exploring further. # CSAT- und Sitzungsexporte > Exportiere einzelne CSAT-Umfragen und erfasste Agenten-Login-Intervalle als paginiertes JSON. Mit der Public API von Chatarmin CX prüfst du einzelne Umfrageergebnisse oder übernimmst erfasste Agenten-Login-Intervalle in dein Berichtssystem. ## Zugriff und Limits Erstelle unter [Einstellungen → API](https://armin.cx/app/_/settings/api) einen API-Schlüssel mit zugewiesenem Support-Agenten. Sende ihn im Header `cx-api-key`. Beide schreibgeschützten Endpoints brauchen `analytics:read` und organisationsweiten Dashboard-Zugriff. Sie bieten keinen eingeschränkten Ersatzexport nur für dich oder dein Team. | Endpoint | Erforderliche Berechtigungen des zugewiesenen Agenten | Zusätzlicher API-Scope | | ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------- | | `GET /public/v1/csat-surveys` | `dashboard.org_metrics` und `dashboard.ticket_csat` | `tickets:read` nur beim Anfordern von Kommentaren | | `GET /public/v1/agent-sessions` | `dashboard.org_metrics` und `dashboard.other_agents_metrics` | Keiner zusätzlich zu `analytics:read` | Ein Filter auf deine eigene Agenten-ID hebt diese Anforderungen nicht auf. Beide Endpoints nutzen das Analytics-Limit von 10 Requests/Minute. Sie liefern JSON, kein CSV/Excel, und verändern weder Tickets noch Sitzungen oder versenden Umfragen. Für aggregierte Bewertungen, Antwortquoten und Online-Zeit nutze [Berichte und Metriken](/de/api/reports). ## CSAT-Umfragen exportieren Wähle einen Datumsbezug: im Zeitraum **eingereichte** oder **versendete** Umfragen, einschließlich noch unbeantworteter. Berücksichtigt werden nur Umfragen auf vorhandenen, nicht gelöschten, nicht importierten Haupttickets im Workspace, keine Side Conversations. | Query-Parameter | Verhalten | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- | | `submitted_from`, `submitted_before` | Vollständiges Datumspaar für Einreichungen, alternativ das Versanddatumspaar. | | `sent_from`, `sent_before` | Vollständiges Versanddatumspaar. Nicht mit Einreichungsparametern kombinieren. | | `credited_agent_id` | Optionale exakte gespeicherte Agenten-ID der Umfrage. IDs sind undurchsichtige Strings, keine UUIDs oder Namen. | | `score_lte` | Optionale ganze Zahl von 1 bis 5, einschließlich. Unbewertete Umfragen passen nicht zu diesem Filter. | | `include_comments` | Exakt `true` oder `false`, standardmäßig `false`. `true` braucht zusätzlich `tickets:read`. | | `limit` | Ganze Zahl von 1 bis 100, standardmäßig 50. | | `cursor` | Optionales Fortsetzungstoken aus `pagination.next_cursor`. | Sende genau ein vollständiges Datumspaar als ISO-8601-Zeitpunkte mit `Z` oder explizitem Offset. Die Untergrenze ist inklusive, die Obergrenze exklusiv: `[from, before)`. Die Obergrenze muss später und höchstens 90 × 24 Stunden nach der Untergrenze liegen. Anders als `UNTIL` in Berichtsabfragen ist `before` kein inklusiver Kalendertag. Unbekannte Query-Parameter werden abgelehnt. Starte mit einem kleinen Export nach Versanddatum ohne Kommentare: ```bash theme={null} curl --get 'https://api.armin.cx/public/v1/csat-surveys' \ -H "cx-api-key: $CX_API_KEY" \ --data-urlencode 'sent_from=2026-08-01T00:00:00Z' \ --data-urlencode 'sent_before=2026-08-08T00:00:00Z' \ --data-urlencode 'limit=100' ``` Für niedrige Bewertungen eines zugeordneten Agenten nutze Einreichungsdaten. Ersetze `agent_example` durch die Agenten-ID deines Workspaces. Fordere Kommentare nur an, wenn deine Integration Kundentext braucht und der Schlüssel den zusätzlichen Scope hat: ```bash theme={null} curl --get 'https://api.armin.cx/public/v1/csat-surveys' \ -H "cx-api-key: $CX_API_KEY" \ --data-urlencode 'submitted_from=2026-08-01T00:00:00Z' \ --data-urlencode 'submitted_before=2026-08-08T00:00:00Z' \ --data-urlencode 'credited_agent_id=agent_example' \ --data-urlencode 'score_lte=3' \ --data-urlencode 'include_comments=true' \ --data-urlencode 'limit=100' ``` ### Umfrageergebnisse lesen Das folgende erfundene Beispiel zeigt die Standardantwort ohne Kommentare. Ergebnisse sind aufsteigend nach dem gewählten Datumsfeld und dann der Umfrage-ID sortiert. `score` und `submitted_at` können `null` sein; auch `ticket_number`, `credited_agent_id` und `credited_agent_name` erlauben `null`. ```json theme={null} { "success": true, "data": [ { "id": "11111111-1111-4111-8111-111111111111", "ticket_id": "22222222-2222-4222-8222-222222222222", "ticket_number": 1234, "credited_agent_id": "agent_example", "credited_agent_name": "Alex Example", "attribution_source": "survey_agent_id", "score": 3, "sent_at": "2026-08-01T09:00:00.000000Z", "submitted_at": "2026-08-02T10:00:00.000000Z" } ], "pagination": { "has_more": false, "next_cursor": null }, "meta": { "attribution": "Stored survey agent_id only; no read-time resolver fallback or historical reattribution. Missing credit remains unattributed.", "comments_included": false, "privacy": "Comments are customer-entered text and may contain personal data. They are opt-in and require tickets:read in addition to analytics:read." } } ``` `credited_agent_id` ist die gespeicherte `agent_id` der Umfrage, keine beim Lesen abgeleitete Zuordnung zum Lösungsagenten oder Bearbeiter. Fehlende Zuordnung bleibt `null` mit `attribution_source: "unattributed"`. Ein Name kann auch bei gespeicherter ID fehlen. Alte Umfragezuordnungen werden nicht umgeschrieben; historische Zuordnung beweist also nicht, wer das Ticket gelöst hat. Bei neuen Umfragen ohne explizit angegebene Zuordnung übernimmt die Standardzuordnung den erfassten `solved_by` des Tickets nur, wenn dessen aktueller Status `resolved` ist und dieser Lösungsagent im selben Workspace zulässig ist. Es gibt keinen Ersatz durch Bearbeiter oder Nachrichtenautor. Der alte Marker `AI` und aus der Analytics-Abrechnung ausgeschlossene KI-Agenten erhalten keine Standardzuordnung, auch nach dem Löschen eines ausgeschlossenen Agenten. Spätere Wiedereröffnung oder Neuzuweisung berechnet diesen Snapshot nicht neu. Die Standardzuordnung kann einen zulässigen KI-Lösungsagenten berücksichtigen; sie garantiert keine rein menschliche Zuordnung. Mit `include_comments=true` enthält jedes Element zusätzlich `comment` als String oder `null`, und `meta.comments_included` ist `true`. Sonst fehlt das Feld vollständig. Kommentare können personenbezogene Daten enthalten: Begrenze nachgelagerte Zugriffe und kopiere sie nicht in Logs. Der Export enthält keine Kundenkontaktdaten, Umfragetokens oder -links und keine Ticketinhalte. ## Agentensitzungen exportieren Prüfe Beginn, Ende und letzte Aktivität erfasster Login-Intervalle. Das sind die bestehenden veränderlichen Login-Sitzungen, kein neuer Speicher für Anwesenheitsereignisse. Der Export enthält keine gespeicherte Pausen- oder Ereignishistorie. | Query-Parameter | Verhalten | | ---------------- | ------------------------------------------------------------------------------------------------------------- | | `from`, `before` | Erforderliche ISO-Zeitpunkte mit Offset, `[from, before)`, mit positiver Dauer von höchstens 90 × 24 Stunden. | | `agent_id` | Optionale exakte Agenten-ID als undurchsichtiger String statt UUID oder Name. | | `limit` | Ganze Zahl von 1 bis 100, standardmäßig 50. | | `cursor` | Optionales Fortsetzungstoken. | ```bash theme={null} curl --get 'https://api.armin.cx/public/v1/agent-sessions' \ -H "cx-api-key: $CX_API_KEY" \ --data-urlencode 'from=2026-08-01T00:00:00Z' \ --data-urlencode 'before=2026-08-08T00:00:00Z' \ --data-urlencode 'agent_id=agent_example' \ --data-urlencode 'limit=100' ``` Der Endpoint wählt **überlappende erfasste Intervalle**, nicht nur im Zeitraum gestartete Sitzungen: `session_start < before` und entweder `session_end > from` oder `session_end` ist `null`. Eine Sitzung mit Ende genau bei `from` oder Beginn genau bei `before` wird ausgeschlossen. Eine vor dem Zeitraum gestartete Sitzung kann enthalten sein. Ursprüngliche Zeitpunkte bleiben ungekürzt; überlappende Datensätze werden nicht vereinigt. Diese erfundene Antwort enthält bewusst einen veralteten offenen Datensatz: ```json theme={null} { "success": true, "data": [ { "id": "33333333-3333-4333-8333-333333333333", "agent_id": "agent_example", "session_start": "2026-07-31T23:00:00.000000Z", "session_end": null, "last_activity": "2026-08-01T00:15:00.000000Z", "updated_at": "2026-08-01T00:15:00.000000Z" } ], "pagination": { "has_more": false, "next_cursor": null }, "meta": { "date_filter": "recorded_interval_overlap", "order_by": "session_start,id", "stale_open_records_included": true, "mutable": true, "break_history_stored": false, "description": "Recorded intervals overlapping the requested range, with original timestamps retained. Stale open records are included; no end is inferred from last_activity. Null session_end is not proof of current availability. These are mutable login sessions, not presence or break events. Replica reads are eventually consistent; pagination is not a snapshot." } } ``` `session_end: null` ist **kein Beweis aktueller Verfügbarkeit**. Prüfe `last_activity` separat; dieser Export leitet daraus nie ein Ende ab. Sitzungszeilen enthalten nur `id`, `agent_id`, `session_start`, `session_end`, `last_activity` und `updated_at`, niemals IP-Adressen, Browserdetails oder User-Agents. Für deduplizierte, auf den Zeitraum begrenzte Online-Sekunden je Zeitabschnitt frage `agent_online_time` über [Berichte und Metriken](/de/api/reports#antworten-und-online-zeit-pro-stunde) ab, statt rohe Dauern zu summieren. ## Export fortsetzen Wenn `pagination.has_more` den Wert `true` hat, nutze `pagination.next_cursor` als `cursor` des nächsten Requests. Stoppe bei `has_more: false`. Behalte Schlüssel, Workspace, zugewiesenen Agenten, Scopes und alle Filter bei, auch `limit` und Kommentaroption. Änderungen machen den Cursor ungültig. Behandle Zeitstempel und Cursor als unveränderte Strings; ein aus einem Zeitstempel nachgebauter Cursor kann Präzision verlieren. Setze für die Abfrage niedriger Bewertungen oben `NEXT_CURSOR` auf das zurückgegebene Token und wiederhole dieselben Parameter: ```bash theme={null} curl --get 'https://api.armin.cx/public/v1/csat-surveys' \ -H "cx-api-key: $CX_API_KEY" \ --data-urlencode 'submitted_from=2026-08-01T00:00:00Z' \ --data-urlencode 'submitted_before=2026-08-08T00:00:00Z' \ --data-urlencode 'credited_agent_id=agent_example' \ --data-urlencode 'score_lte=3' \ --data-urlencode 'include_comments=true' \ --data-urlencode 'limit=100' \ --data-urlencode "cursor=$NEXT_CURSOR" ``` Sitzungen werden genauso paginiert, aufsteigend nach `session_start` und dann `id`. Keiner der Exporte ist ein eingefrorener Snapshot: Replikatlesevorgänge sind zeitverzögert konsistent, Umfrageantworten können später eintreffen und Sitzungsenden oder Aktivitätszeitpunkte sich während der Pagination ändern. Für laufende Importe lies begrenzte überlappende Zeitfenster erneut und aktualisiere nachgelagerte Zeilen über `id`; dies ist kein Änderungsereignis-Feed. Bei direkt angrenzenden Zeitfenstern wird das bisherige `before` zum nächsten `from`. ## Fehlerbehebung | Antwort oder Symptom | Was du prüfen solltest | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `401` | Sende einen gültigen API-Schlüssel. | | `403 FORBIDDEN_SCOPE` | Prüfe zugewiesenen Agenten, `analytics:read`, beide nötigen Dashboard-Berechtigungen und `tickets:read` für Kommentare. Ein engerer Agentenfilter umgeht den organisationsweiten Zugriffsschutz nicht. | | `400 VALIDATION_ERROR` | Nutze nur unterstützte Parameter und genau ein vollständiges Datumspaar, gültige Offsets, steigende Grenzen innerhalb von 90 Tagen und `limit` höchstens 100. Behalte Cursor-Parameter unverändert bei. | | `429` | Warte auf `Retry-After`; siehe [Rate Limits](/de/api/rate-limits). | | Export und Bericht ergeben unterschiedliche Summen | Prüfe Versand- gegen Einreichungsdatum, gespeicherte Zuordnung, aktuelle Ticketzulässigkeit, Replikataktualität und Abdeckung der Berichtsprojektion. Es sind keine austauschbaren Audit-Snapshots. | Scheitert ein kleiner gültiger Request weiterhin, kontaktiere den Support mit der `request_id`, dem Endpoint und bereinigten Filtern. Teile weder API-Schlüssel noch Kundenkommentare in Diagnose-Logs.