---
title: "Berichte"
description: "Incident-Bericht (Volumen, MTTA, MTTR nach Team, Schweregrad oder Monat) und On-Call-Bericht (Minuten pro Person) für einen Zeitraum, als JSON oder CSV."
---

Zwei Berichte über einen expliziten Zeitraum, jeweils als JSON oder als CSV-Download.

## Authentifizierung

Jede IM-berechtigte Rolle (`admin`, `editor`, `responder`) oder ein organisationsweiter API-Token. Incident Management muss für die Organisation aktiviert sein.

## Zeitraum

Beide Berichte verlangen `from` und `to` als ISO 8601. `from` zählt mit, `to` nicht, `to` muss nach `from` liegen, und der Zeitraum darf höchstens 400 Tage umfassen.

## Incident-Bericht

`GET /api/im/reports/incidents`

Zählt die im Zeitraum ausgelösten Incidents und ihre mittlere Zeit bis zur Bestätigung (MTTA) und bis zur Lösung (MTTR), in Minuten. Ein Incident, der nie bestätigt oder gelöst wurde, fällt aus dem jeweiligen Durchschnitt heraus, er zählt nicht als null. Test-Incidents zählen nicht mit.

### Query-Parameter

| Parameter | Typ | Erforderlich | Beschreibung |
|-----------|------|----------|--------------|
| `from`, `to` | ISO 8601 | Ja | Siehe [Zeitraum](#zeitraum). |
| `groupBy` | string | Nein | `month` (Standard), `team` oder `severity`. Jeder andere Wert fällt auf `month` zurück. |
| `tz` | number | Nein | Dein UTC-Versatz in Minuten (z. B. `120`), Standard `0`. Entscheidet, in welchen lokalen Monat ein Incident fällt. |
| `format` | string | Nein | `csv` liefert eine CSV-Datei statt JSON. |

### Beispiel (cURL)

```bash
curl "$BASE_URL/api/im/reports/incidents?from=2026-07-01T00:00:00Z&to=2026-10-01T00:00:00Z&groupBy=severity" \
  -H "Authorization: Bearer $TOKEN"
```

### Antwort (Response)

```json
{
  "from": "2026-07-01T00:00:00.000Z",
  "to": "2026-10-01T00:00:00.000Z",
  "groupBy": "severity",
  "summary": { "count": 27, "mttaMinutes": 6.4, "mttrMinutes": 82.15 },
  "groups": [
    { "groupKey": "sev1", "groupLabel": "sev1", "count": 3, "mttaMinutes": 1.8, "mttrMinutes": 41.5 },
    { "groupKey": "sev3", "groupLabel": "sev3", "count": 24, "mttaMinutes": 7.1, "mttrMinutes": 87.24 }
  ]
}
```

`groupKey` / `groupLabel` je Gruppierung: `team` liefert Team-ID und Teamname, `severity` liefert `sev1` bis `sev4`, `month` liefert in beiden Feldern den UTC-Zeitpunkt des lokalen Monatsbeginns (z. B. `2026-08-31T22:00:00.000Z` für August bei `tz=120`). Gruppen ohne Incidents fehlen. Durchschnitte sind auf zwei Nachkommastellen gerundet und `null`, wenn kein Incident der Gruppe in Frage kommt.

Mit `format=csv` ist die Antwort `text/csv` mit `Content-Disposition: attachment; filename="incidents-report-<date>.csv"` und den Spalten `<groupBy>,count,mttaMinutes,mttrMinutes`. Monate stehen als `YYYY-MM` darin, leere Durchschnitte als leere Zellen. Die Zusammenfassung ist nicht Teil der CSV.

## On-Call-Bericht

`GET /api/im/reports/on-call`

On-Call-Minuten pro Person innerhalb des Zeitraums. Schichten, die vor `from` beginnen oder nach `to` enden, zählen nur mit ihrem Anteil im Zeitraum. Team-Overrides vom Typ `online` (ohne Schedule) kommen zu den geplanten Schichten hinzu.

### Query-Parameter

| Parameter | Typ | Erforderlich | Beschreibung |
|-----------|------|----------|--------------|
| `from`, `to` | ISO 8601 | Ja | Siehe [Zeitraum](#zeitraum). |
| `format` | string | Nein | `csv` liefert eine CSV-Datei statt JSON. |

### Beispiel (cURL)

```bash
curl "$BASE_URL/api/im/reports/on-call?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"
```

### Antwort (Response)

```json
{
  "periodStart": "2026-09-01T00:00:00.000Z",
  "periodEnd": "2026-10-01T00:00:00.000Z",
  "users": [
    { "userId": "u_abc123", "userName": "Jana Weber", "minutes": 21600 },
    { "userId": "u_def456", "userName": "Tobias Brandt", "minutes": 21600 }
  ]
}
```

`users` ist nach `userId` sortiert, `minutes` auf zwei Nachkommastellen gerundet. Personen ohne On-Call-Zeit im Zeitraum fehlen.

Mit `format=csv` ist die Antwort `text/csv` mit `Content-Disposition: attachment; filename="on-call-report-<date>.csv"` und den Spalten `userId,userName,minutes,hours`.

## Häufige Fehler

- `401 Unauthorized` (`unauthorized`) wenn du nicht authentifiziert bist
- `403 Forbidden` (`customerScopedTokenForbidden`) bei einem kunden-gescopten Token
- `403 Forbidden` (`imAccessDenied`) wenn deine Session keine IM-berechtigte Rolle hat
- `403 Forbidden` (`imNotEnabled`) wenn Incident Management für die Organisation nicht aktiviert ist
- `400 Bad Request` (`imReportRangeRequired`) wenn `from` oder `to` fehlt oder kein gültiges Datum ist
- `400 Bad Request` (`imReportRangeInvalid`) wenn `from` nicht vor `to` liegt
- `400 Bad Request` (`imReportRangeTooLarge`) wenn der Zeitraum 400 Tage überschreitet