---
title: "Eskalationsstufen"
description: "Die Eskalationskette eines Teams lesen und bearbeiten: geordnete Stufen, ihre Einstellungen für automatische Eskalation und Wiederholung, und die Schedules unter jeder Stufe."
---

Die Eskalationskette eines Teams ist eine geordnete Liste von **Stufen** (Tiers). Stufe 1 wird zuerst alarmiert; Bereitschaft in einer Stufe hat, wen die Schedules der Stufe gerade in Schicht haben. Jede Stufe legt fest, ob und wann der Incident zur nächsten Stufe weiterwandert und wie oft die Stufe vorher erneut alarmiert wird. Wiederholungen der ganzen Kette stehen am Team ([Team ändern](/de/api/incident-management/teams)).

## Authentifizierung

Basis-IM-Zugriff: eine IM-berechtigte Rolle oder ein organisationsweiter API-Token, und Incident Management für die Organisation aktiviert. Die Kette lesen darf jeder mit diesem Zugriff. Jedes Schreiben braucht die Team-Schreibhürde: Organisationsrolle `admin`, oder Team-Admin dieses Teams. Ein API-Token läuft mit der Rolle des Users, der ihn erstellt hat, also kommt nur ein Token durch, den ein Organisations-Admin erstellt hat.

## Stufenfelder

| Feld | Typ | Beschreibung |
|-------|------|-------------|
| `tierOrder` | integer | Position in der Kette, 1 = wird zuerst alarmiert. Änderbar nur über [Neu ordnen](#stufen-neu-ordnen). |
| `autoEscalationEnabled` | boolean | Ob der Incident automatisch zur nächsten Stufe weiterwandert. Standard `true`. |
| `autoEscalationAfterMinutes` | integer | Minuten bis zum Weiterwandern, `0` oder mehr. Standard `5`. |
| `autoEscalationStopMode` | string | `acknowledged` oder `resolved`: der Incident-Zustand, der die Eskalation stoppt. Standard `acknowledged`. |
| `autoEscalationSeverities` | array \| null | Schweregrade, die automatisch eskalieren: eine Teilmenge von `critical`, `warning`, `minor`. `null` = alle. |
| `autoEscalationTimeFilters` | array | Wochenfenster, in denen die automatische Eskalation greifen darf, bis zu 50, jeweils `{ from: "HH:mm", until: "HH:mm", days: number[] }` mit ISO-Wochentagen (1 = Montag). `until` darf `"24:00"` sein. `[]` = immer. |
| `repeats` | integer | Wie oft diese Stufe vor dem Weiterwandern noch einmal alarmiert wird, `0` oder mehr. Standard `0`. |
| `repeatsAfterMinutes` | integer \| null | Minuten zwischen diesen Wiederholungen. `null` = `autoEscalationAfterMinutes` verwenden. |
| `repeatsStopMode` | string | `acknowledged` oder `resolved`: der Incident-Zustand, der die Wiederholungen stoppt. Standard `acknowledged`. |

## Eskalationskette lesen

`GET /api/im/teams/:id/escalations`

Liefert alle Stufen in Reihenfolge, jede mit ihren Schedules, Rotationsgruppen und Mitgliedern, dazu die Eskalationseinstellungen des Teams.

### Beispiel (cURL)

```bash
curl -X GET "$BASE_URL/api/im/teams/3/escalations" \
  -H "Authorization: Bearer $TOKEN"
```

### Antwort (Response)

`200 OK`

```json
{
  "tiers": [
    {
      "id": 21,
      "tierOrder": 1,
      "autoEscalationEnabled": true,
      "autoEscalationAfterMinutes": 5,
      "autoEscalationStopMode": "acknowledged",
      "autoEscalationSeverities": null,
      "autoEscalationTimeFilters": [],
      "repeats": 0,
      "repeatsAfterMinutes": null,
      "repeatsStopMode": "acknowledged",
      "schedules": [
        {
          "id": 7,
          "displayName": "Primary On-Call",
          "timezone": "Europe/Berlin",
          "effectiveFrom": null,
          "effectiveUntil": null,
          "weeklySchedules": [],
          "rotationMode": "explicit",
          "rotationRepeats": "weekly",
          "customRepeatUnit": null,
          "customRepeatValue": null,
          "autoRotationSize": null,
          "roundRobinSize": 1,
          "startsOnDayOfWeek": 1,
          "startsOnDateOfMonth": null,
          "startsOnTime": "09:00",
          "rotations": [
            {
              "id": 12,
              "rotationOrder": 1,
              "members": [
                { "userId": "u_abc123", "userName": "Ada Lovelace", "userImage": null, "memberOrder": 1 }
              ]
            }
          ]
        }
      ]
    }
  ],
  "teamSettings": {
    "timezone": "Europe/Berlin",
    "escalationRepeats": 1,
    "escalationRepeatsAfterMinutes": 15,
    "escalationRepeatsStopMode": "acknowledged",
    "engagementReportEnabled": false,
    "engagementReportDayOfWeek": null,
    "engagementReportTime": null
  }
}
```

Die Schedule-Felder sind unter [Rotationskadenz](/de/api/incident-management/schedules#rotationskadenz) und [Schedule aktualisieren](/de/api/incident-management/update-schedule) erklärt.

## Stufe hinzufügen

`POST /api/im/teams/:id/tiers`

Hängt eine Stufe ans Ende der Kette (`tierOrder` = höchste + 1), mit den Standardwerten aus der Tabelle oben. Im selben Schritt entsteht ein Schedule unter der Stufe: Name `Tier N schedule`, 24/7, `rotationMode: "none"`, in der Zeitzone des Teams (oder `UTC`, wenn das Team keine hat), mit einer Rotationsgruppe, die die angegebenen Mitglieder in der angegebenen Reihenfolge enthält.

### Anfrage (Request Body)

| Feld | Typ | Erforderlich | Beschreibung |
|-------|------|----------|-------------|
| `memberUserIds` | string[] | Ja | 1 bis 200 verschiedene User-IDs, alle Mitglieder dieses Teams. |

### Beispiel (cURL)

```bash
curl -X POST "$BASE_URL/api/im/teams/3/tiers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "memberUserIds": ["u_abc123", "u_def456"] }'
```

### Antwort (Response)

`200 OK`: die Stufenfelder plus `schedules` mit dem einen neuen Schedule, in derselben Form wie in der Eskalationskette (Mitglieder ohne `userImage`).

```json
{
  "id": 22,
  "tierOrder": 2,
  "autoEscalationEnabled": true,
  "autoEscalationAfterMinutes": 5,
  "autoEscalationStopMode": "acknowledged",
  "autoEscalationSeverities": null,
  "autoEscalationTimeFilters": [],
  "repeats": 0,
  "repeatsAfterMinutes": null,
  "repeatsStopMode": "acknowledged",
  "schedules": [
    {
      "id": 8,
      "displayName": "Tier 2 schedule",
      "timezone": "Europe/Berlin",
      "effectiveFrom": null,
      "effectiveUntil": null,
      "weeklySchedules": [],
      "rotationMode": "none",
      "rotationRepeats": null,
      "customRepeatUnit": null,
      "customRepeatValue": null,
      "autoRotationSize": null,
      "roundRobinSize": 1,
      "startsOnDayOfWeek": null,
      "startsOnDateOfMonth": null,
      "startsOnTime": null,
      "rotations": [
        {
          "id": 14,
          "rotationOrder": 1,
          "members": [
            { "userId": "u_abc123", "userName": "Ada Lovelace", "memberOrder": 1 },
            { "userId": "u_def456", "userName": "Bob Fixit", "memberOrder": 2 }
          ]
        }
      ]
    }
  ]
}
```

## Stufe ändern

`PATCH /api/im/teams/:id/tiers/:tierId`

Jedes Feld aus der Tabelle [Stufenfelder](#stufenfelder) außer `tierOrder` ist optional und änderbar. Nur die im Body vorhandenen Felder ändern sich.

### Beispiel (cURL)

```bash
curl -X PATCH "$BASE_URL/api/im/teams/3/tiers/21" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "autoEscalationAfterMinutes": 10,
    "autoEscalationSeverities": ["critical"],
    "autoEscalationTimeFilters": [{ "from": "18:00", "until": "08:00", "days": [1, 2, 3, 4, 5] }]
  }'
```

### Antwort (Response)

`200 OK`: die Stufenfelder nach der Änderung (ohne `schedules`).

## Stufe löschen

`DELETE /api/im/teams/:id/tiers/:tierId`

Löscht die Stufe samt ihren Schedules, Rotationsgruppen und Schichten. Die übrigen Stufen behalten ihre `tierOrder`; wer Stufe 2 von 3 löscht, behält die Positionen 1 und 3. Mit [Neu ordnen](#stufen-neu-ordnen) schließt du die Lücke, falls du fortlaufende Nummern brauchst.

### Beispiel (cURL)

```bash
curl -X DELETE "$BASE_URL/api/im/teams/3/tiers/22" \
  -H "Authorization: Bearer $TOKEN"
```

### Antwort (Response)

`200 OK`

```json
{ "success": true }
```

## Stufen neu ordnen

`POST /api/im/teams/:id/tiers/reorder`

Nummeriert die Kette in der gesendeten Reihenfolge auf `1..n` um.

### Anfrage (Request Body)

| Feld | Typ | Erforderlich | Beschreibung |
|-------|------|----------|-------------|
| `tierIds` | number[] | Ja | Jede Stufen-ID dieses Teams genau einmal, in der neuen Reihenfolge. |

### Beispiel (cURL)

```bash
curl -X POST "$BASE_URL/api/im/teams/3/tiers/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tierIds": [22, 21] }'
```

### Antwort (Response)

`200 OK`

```json
{ "tiers": [{ "id": 22, "tierOrder": 1 }, { "id": 21, "tierOrder": 2 }] }
```

## Schedule zu einer Stufe hinzufügen

`POST /api/im/teams/:id/tiers/:tierId/schedules`

Legt einen weiteren Schedule unter einer Stufe an, etwa einen Follow-the-Sun-Schedule in einer anderen Zeitzone, mit Kadenz und Rotationsgruppen in einem Aufruf. Bereitschaft in einer Stufe hat, wen irgendeiner ihrer Schedules gerade in Schicht hat.

### Anfrage (Request Body)

| Feld | Typ | Erforderlich | Beschreibung |
|-------|------|----------|-------------|
| `name` | string | Ja | 1 bis 120 Zeichen nach dem Trimmen. |
| `timezone` | string | Ja | IANA-Zone, in der der Schedule ausgewertet wird. |
| `effectiveFrom` | string \| null | Nein | ISO-Zeitstempel, vor dem der Schedule niemanden alarmiert. |
| `effectiveUntil` | string \| null | Nein | ISO-Zeitstempel, nach dem der Schedule niemanden alarmiert. |
| `weeklySchedules` | array | Nein | Bereitschaftsfenster, gleiche Form wie `autoEscalationTimeFilters`. Weggelassen oder `[]` = 24/7. |
| `rotations` | array | Nein | Rotationsgruppen, bis zu 50, jeweils `{ members: string[] }` mit bis zu 200 verschiedenen Mitgliedern dieses Teams. Die Array-Reihenfolge ist die Rotationsreihenfolge. |

Dazu die Kadenzfelder aus [Rotationskadenz](/de/api/incident-management/schedules#rotationskadenz). Weggelassene Kadenzfelder stehen auf `rotationMode: "none"`, `roundRobinSize: 1`, alles andere `null`. Die resultierende Kadenz wird als Ganzes validiert.

### Beispiel (cURL)

```bash
curl -X POST "$BASE_URL/api/im/teams/3/tiers/21/schedules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "APAC Follow-the-Sun",
    "timezone": "Asia/Singapore",
    "weeklySchedules": [{ "from": "09:00", "until": "18:00", "days": [1, 2, 3, 4, 5] }],
    "rotationMode": "explicit",
    "rotationRepeats": "weekly",
    "startsOnDayOfWeek": 1,
    "startsOnTime": "09:00",
    "rotations": [{ "members": ["u_abc123"] }, { "members": ["u_def456"] }]
  }'
```

### Antwort (Response)

`200 OK`: der neue Schedule in derselben Form wie in der Eskalationskette (Mitglieder ohne `userImage`).

## Häufige Fehler

- `401 Unauthorized` (`unauthorized`) wenn du nicht authentifiziert bist
- `403 Forbidden` (`imAccessDenied`) bei einem kunden-gescopten Token, oder wenn deine Session keine IM-berechtigte Rolle hat
- `403 Forbidden` (`imNotEnabled`) wenn Incident Management für die Organisation nicht aktiviert ist
- `403 Forbidden` (`imTeamWriteDenied`) bei jedem Schreiben, wenn du weder Organisations-Admin noch Team-Admin dieses Teams bist
- `404 Not Found` (`imTeamNotFound`) wenn das Team nicht existiert oder zu einer anderen Organisation gehört
- `404 Not Found` (`imEscalationTierNotFound`) wenn `:tierId` keine Stufe dieses Teams ist
- `404 Not Found` (`imTeamMemberNotFound`) wenn eine User-ID in `memberUserIds` oder `rotations` kein Mitglied dieses Teams ist
- `400 Bad Request` (`invalidRequestBody`) wenn eine Pfad-ID keine positive Ganzzahl ist, `memberUserIds` fehlt, leer ist oder eine leere ID enthält, `tierIds` fehlt, leer ist oder nicht aus verschiedenen positiven Ganzzahlen besteht, `name` oder `timezone` fehlt oder ungültig ist, `effectiveFrom`/`effectiveUntil` kein gültiger Zeitstempel ist, oder `rotations` fehlerhaft ist
- `422 Unprocessable Entity` (`imTierReorderMismatch`) wenn `tierIds` nicht genau die Stufen-IDs dieses Teams enthält
- `422 Unprocessable Entity` (`imInvalidRequestBody`) wenn `autoEscalationEnabled` kein Boolean ist
- `422 Unprocessable Entity` (`imInvalidNumber`) wenn `autoEscalationAfterMinutes`, `repeats` oder `repeatsAfterMinutes` keine Ganzzahl ab `0` ist, oder eine Kadenzzahl keine Ganzzahl ab `1`
- `422 Unprocessable Entity` (`imInvalidStopMode`) wenn ein Stop-Modus nicht `acknowledged` oder `resolved` ist
- `422 Unprocessable Entity` (`imInvalidSeverities`) wenn `autoEscalationSeverities` weder `null` noch eine Liste aus `critical`, `warning`, `minor` ist
- `422 Unprocessable Entity` (`imInvalidTimeFilter`) wenn eine Fensterliste kein Array ist, mehr als 50 Einträge hat, oder ein Eintrag kein Objekt ist oder kein `days`-Array hat
- `422 Unprocessable Entity` (`imInvalidTimeOfDay`) wenn `from`/`until` eines Fensters oder `startsOnTime` nicht `"HH:mm"` ist
- `422 Unprocessable Entity` (`imInvalidDayOfWeek`) wenn ein Fenstertag oder `startsOnDayOfWeek` nicht 1 bis 7 ist
- `422 Unprocessable Entity` (`imInvalidRotationMode`) wenn `rotationMode` nicht `none`, `auto` oder `explicit` ist
- `422 Unprocessable Entity` (`imInvalidRotation`) wenn die Kadenz nicht zusammenpasst, eine Liste mehr als 200 Mitglieder oder 50 Rotationsgruppen hat, oder eine User-ID in einer Liste doppelt vorkommt
- `409 Conflict` (`imTierOrderConflict`) wenn zwei Stufen im selben Moment angelegt wurden; erneut versuchen