> ## 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.

# Ticket-Exporte

> Exportiere Tickets und ihre Nachrichten im Hintergrund als CSV-Dateien, nach gespeicherter Ansicht, Zeitraum oder Ticket-IDs.

Mit der Public API von Chatarmin CX lädst du viele Tickets samt Nachrichten auf einmal. Du startest einen Export mit einer Anfrage, fragst den Status ab, bis er fertig ist, und lädst das Ergebnis über einen zeitlich begrenzten Link herunter. Du musst Nachrichten nicht mehr Ticket für Ticket lesen.

## So funktioniert es

1. `POST /public/v1/ticket-exports` legt den Export an und gibt ihn sofort mit Status `queued` zurück.
2. Der Export läuft im Hintergrund und umfasst so viele Tickets, wie du wählst, bis zu 50.000.
3. `GET /public/v1/ticket-exports/{exportId}` liefert den Status. Bei `completed` enthält die Antwort auch eine `download_url`.
4. Du lädst die Datei über `download_url` herunter.

Beide Endpoints brauchen den Scope `tickets:export`. Erstelle einen Schlüssel unter [Einstellungen → API](https://armin.cx/app/_/settings/api). Ein mit einem Agenten verknüpfter Schlüssel exportiert nur gespeicherte Ansichten, die dieser Agent im Posteingang sieht, wie bei [`GET /views`](https://docs.armin.cx/de/api/filtering-and-saved-views). Ein Schlüssel ohne verknüpften Agenten kann jede Ansicht der Organisation exportieren.

## Nächtlicher Sync

Exportiere einmal pro Nacht die Tickets einer gespeicherten Ansicht samt Nachrichten.

**1. Ansicht finden**

Rufe `GET /public/v1/views` auf und merke dir die `id` der Ansicht mit den Tickets, die du synchronisierst. Siehe [Filtern und gespeicherte Ansichten](https://docs.armin.cx/de/api/filtering-and-saved-views.md).

**2. Export anlegen**

```bash theme={null}
curl -X POST 'https://api.armin.cx/public/v1/ticket-exports' \
  -H "cx-api-key: $CX_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "view_id": "00000000-0000-4000-8000-0000000000a1", "include_messages": true }'
```

Die Antwort hat Status `202` und enthält den Export mit Status `queued`.

**3. Warten, bis er fertig ist**

```bash theme={null}
curl "https://api.armin.cx/public/v1/ticket-exports/$EXPORT_ID" \
  -H "cx-api-key: $CX_API_KEY"
```

Es gibt keine Webhooks. Frage alle paar Sekunden ab, bis `status` `completed` oder `failed` ist.

**4. Datei herunterladen**

Lade `data.download_url` herunter und entpacke die Datei. Jede Statusabfrage eines abgeschlossenen Exports liefert einen neuen Link. Frage den Status also erneut ab, wenn ein Link abgelaufen ist.

## Backfill

Exportiere alle Tickets, die in einem Zeitraum erstellt wurden. Datumsangaben haben das Format `YYYY-MM-DD` in UTC, beide Tage sind eingeschlossen, und es wird nach dem Erstellungsdatum des Tickets gefiltert.

```bash theme={null}
curl -X POST 'https://api.armin.cx/public/v1/ticket-exports' \
  -H "cx-api-key: $CX_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "date_from": "2026-08-01", "date_to": "2026-08-14", "include_messages": true }'
```

Ein Export enthält höchstens 50.000 Tickets. Trifft ein Zeitraum auf mehr, schlägt die Anfrage mit `EXPORT_TOO_LARGE` fehl. Teile den Zeitraum in kleinere Zeiträume und lege pro Zeitraum einen Export an.

## Request-Felder

Wähle genau einen der drei Auswahlmodi. Unbekannte Felder werden mit `400 VALIDATION_ERROR` abgelehnt.

| Feld | Verhalten |
| - | - |
| `view_id` | UUID einer gespeicherten Ansicht. Exportiert alle Tickets der Ansicht. |
| `ticket_ids` | 1 bis 500 Ticket-UUIDs. Existiert eine ID in deiner Organisation nicht, schlägt die Anfrage mit `400 VALIDATION_ERROR` fehl und listet sie in `details.invalid_ticket_ids`. |
| `date_from`, `date_to` | Nur zusammen, `YYYY-MM-DD`, UTC, einschließlich, `date_from` am oder vor `date_to`. |
| `include_messages` | Boolean, standardmäßig `false`. Fügt `messages.csv` hinzu. |
| `columns` | Optionale Liste von Ticket-Spalten für `tickets.csv`. Standardmäßig die Standardspalten. |

Standardspalten: `ticket_number`, `subject`, `contact_first_name`, `contact_last_name`, `contact_email`, `contact_phone`, `status`, `assigned_agent_name`, `created_at`, `updated_at`.

Optionale Spalten: `priority`, `channel`, `channel_name`, `tags`, `last_message_at`, `message_count`, `ticket_url`, `csat_score`, `csat_comment`, `csat_survey_sent`, `csat_submitted_at`, `created_date`, `created_time`, `language`, `social_thread_type`, `social_post_type`, `team_name`, `first_resolved_at`, `resolved_at`.

## Export lesen

```json theme={null}
{
  "success": true,
  "data": {
    "id": "01a1adf2-20b3-72db-a67c-b1fc3cb46be2",
    "status": "completed",
    "created_at": "2026-11-05T23:01:28.884Z",
    "completed_at": "2026-11-05T23:01:38.519Z",
    "expires_at": "2026-11-12T23:01:38.515Z",
    "ticket_count": 144,
    "download_url": "https://…",
    "error": null
  }
}
```

| Feld | Bedeutung |
| - | - |
| `id` | Export-ID. Nutze sie in `GET /ticket-exports/{exportId}`. |
| `status` | `queued`, `processing`, `completed`, `failed` oder `expired`. |
| `created_at`, `completed_at` | ISO-8601-Zeitstempel. `completed_at` ist `null`, bis der Export fertig ist. |
| `expires_at` | Zeitpunkt, an dem die Datei gelöscht wird. `null`, bis der Export abgeschlossen ist. |
| `ticket_count` | Anzahl der Tickets in der Datei. `null`, bis der Export abgeschlossen ist. |
| `download_url` | Nur gesetzt, wenn `status` `completed` ist. 1 Stunde gültig. |
| `error` | Nur gesetzt, wenn `status` `failed` ist: `Export failed. Please create a new export.` |

| Status | Bedeutung |
| - | - |
| `queued` | Der Export wartet auf einen freien Worker. |
| `processing` | Die Datei wird erstellt. |
| `completed` | Die Datei ist fertig. Lade sie über `download_url` herunter. |
| `failed` | Der Export konnte nicht erstellt werden. Lege einen neuen Export an. |
| `expired` | Die Datei hat die Aufbewahrung von 7 Tagen überschritten und ist nicht mehr verfügbar. Lege einen neuen Export an. |

## Die Datei

Ist `include_messages` `true`, ist der Download ein ZIP mit `tickets.csv` und `messages.csv`. Sonst ist der Download eine einzelne `tickets.csv`. Die Dateien sind UTF-8 ohne Byte-Order-Mark. Trifft die Auswahl keine Tickets, wird der Export trotzdem abgeschlossen, mit Dateien, die nur die Kopfzeile enthalten.

Tickets sind nach Erstellungsdatum sortiert, älteste zuerst. Nachrichten sind nach Ticket und dann nach Erstellungsdatum sortiert, älteste zuerst. Interne Notizen und gelöschte Nachrichten sind nicht enthalten.

`messages.csv` hat diese Spalten:

| Spalte | Wert |
| - | - |
| `ticket_id`, `ticket_number` | Das Ticket, zu dem die Nachricht gehört. |
| `created_at` | ISO-8601-Zeitstempel in UTC. |
| `direction` | `inbound` für Kundennachrichten, `outbound` für alle anderen. |
| `author_type` | `customer`, `agent` oder `ai`. |
| `author_name` | Name des Absenders. |
| `ai_agent_name` | Name des KI-Agenten bei `ai`-Nachrichten, sonst leer. |
| `body_text` | Die Nachricht als reiner Text, identisch zu `text` in [`GET /tickets/:ticketNumber/messages`](https://docs.armin.cx/de/api/endpoints), ohne Längenlimit. |
| `message_id` | Nachrichten-ID. |

Alle Zeitstempel in beiden Dateien sind ISO-8601 in UTC. Es gibt keine Zeitzonen-Option.

## Limits

| Limit | Wert |
| - | - |
| Tickets pro Export | 50.000. Darüber schlägt die Anfrage mit `EXPORT_TOO_LARGE` fehl. |
| `ticket_ids` pro Anfrage | 500 |
| Aktive Exporte pro Organisation | 2 (`queued` oder `processing`). Eine dritte Anfrage schlägt mit `EXPORT_LIMIT_REACHED` fehl. |
| Aufbewahrung der Datei | 7 Tage. Danach ist der Status `expired`. |
| Download-Link | Bei jeder Statusabfrage ein neuer Link, 1 Stunde gültig. |
| Export anlegen | 30 Requests/Minute |
| Status abfragen | 120 Requests/Minute |

Siehe [Rate Limits](https://docs.armin.cx/de/api/rate-limits.md).

## Unterschiede zum Legacy-Export

`POST /public/tickets/export` bleibt verfügbar. Wenn du auf den v1-Export umsteigst, ändert sich Folgendes.

| | Legacy-Export | v1-Export |
| - | - | - |
| Auslieferung | Die Datei ist die Antwort der Anfrage | Hintergrund-Job: anlegen, abfragen, herunterladen |
| Größter Export | 500 Tickets | 50.000 Tickets |
| Gelöschte Nachrichten | Enthalten | Nicht enthalten |
| `direction` | `in` / `out` | `inbound` / `outbound` |
| `author_type` | `customer` / `business` / `ai` | `customer` / `agent` / `ai` |
| Zeitstempel | `yyyy-MM-dd hh:mm:ss a zzz` in einer angegebenen Zeitzone | ISO-8601 UTC, keine Option `timezone` |
| `body_text` | Bereinigter Text | Derselbe reine Text wie `text` der v1-Nachricht, ohne Längenlimit |
| Keine Tickets gefunden | `404` | Wird mit Dateien abgeschlossen, die nur die Kopfzeile enthalten |
| Auswahl | `ticketIds` oder `date_from` und `date_to` | `ticket_ids`, `date_from` und `date_to` oder `view_id` |
| Formate | `csv`, `excel`, `eml` | Nur CSV |

In v1 nicht unterstützt: `excel`, `eml`, `order`, `timezone` und `include_ticket_fields`. Die Spaltennamen in `tickets.csv` und `messages.csv` sind dieselben wie im Legacy-Export.

## Fehler

| Antwort | Wann |
| - | - |
| `400 VALIDATION_ERROR` | Nicht genau ein Auswahlmodus, unbekannte Felder oder Spalten, `date_from` nach `date_to` oder `ticket_ids`, die nicht existieren (`details.invalid_ticket_ids`). |
| `400 EXPORT_TOO_LARGE` | Die Auswahl trifft mehr als 50.000 Tickets (`details.max_tickets`). Teile den Zeitraum. |
| `403 FORBIDDEN_SCOPE` | Der Schlüssel hat `tickets:export` nicht. |
| `404 VIEW_NOT_FOUND` | Die Ansicht existiert nicht oder ist für den Agenten des Schlüssels nicht sichtbar. |
| `404 EXPORT_NOT_FOUND` | Der Export existiert in deiner Organisation nicht. |
| `429 EXPORT_LIMIT_REACHED` | Es laufen bereits zwei Exporte, oder ein weiterer Export wird gerade angelegt. Warte kurz und versuche es erneut. |
| `429 RATE_LIMIT_EXCEEDED` | Du hast zu viele Requests gesendet. Warte auf `Retry-After`. |

Das Fehlerformat steht unter [Fehler](https://docs.armin.cx/de/api/errors.md). Werte `code` aus, nicht `message`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.