Skip to Content
Uptimeify Docs

Eskalationsstufen

Die Eskalationskette eines Teams lesen, bearbeiten und testen: geordnete Stufen, ihre Einstellungen für automatische Eskalation und Wiederholung, die Schedules unter jeder Stufe und ein Probelauf, wer alarmiert würde.

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

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

FeldTypBeschreibung
tierOrderintegerPosition in der Kette, 1 = wird zuerst alarmiert. Änderbar nur über Neu ordnen.
autoEscalationEnabledbooleanOb der Incident automatisch zur nächsten Stufe weiterwandert. Standard true.
autoEscalationAfterMinutesintegerMinuten bis zum Weiterwandern, 0 oder mehr. Standard 5.
autoEscalationStopModestringacknowledged oder resolved: der Incident-Zustand, der die Eskalation stoppt. Standard acknowledged.
autoEscalationSeveritiesarray | nullSchweregrade, die automatisch eskalieren: eine Teilmenge von critical, warning, minor. null = alle.
autoEscalationTimeFiltersarrayWochenfenster, 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.
repeatsintegerWie oft diese Stufe vor dem Weiterwandern noch einmal alarmiert wird, 0 oder mehr. Standard 0.
repeatsAfterMinutesinteger | nullMinuten zwischen diesen Wiederholungen. null = autoEscalationAfterMinutes verwenden.
repeatsStopModestringacknowledged 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)

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

Antwort (Response)

200 OK

{
  "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 und Schedule aktualisieren erklärt.

Stufe lesen

GET /api/im/teams/:id/tiers/:tierId

Liest eine Stufe mit ihren Schedules, Rotationen und Mitgliedern zurück, in derselben Form wie ein Eintrag von tiers unter Eskalationskette lesen. Jede IM-berechtigte Rolle darf ihn aufrufen.

Beispiel (cURL)

curl "$BASE_URL/api/im/teams/3/tiers/7" \
  -H "Authorization: Bearer $TOKEN"

Antwort

200 OK, ein Stufenobjekt wie in tiers[] oben. 404 mit imEscalationTierNotFound, wenn :tierId keine Stufe dieses Teams ist.

Stufe hinzufügen

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

Hängt eine Stufe ans Ende der Kette (tierOrder = höchste + 1) oder fügt sie an der Position aus tierOrder ein. Jedes Stufenfeld außer tierOrder lässt sich in derselben Anfrage setzen, mit denselben Namen und derselben Prüfung wie bei Stufe ändern; ein weggelassenes Feld bekommt den Standardwert 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)

FeldTypErforderlichBeschreibung
memberUserIdsstring[]Ja1 bis 200 verschiedene User-IDs, alle Mitglieder dieses Teams.
tierOrderintegerNeinPosition der neuen Stufe, 1 bis höchste + 1. Jede Stufe ab dieser Position rückt im selben Schritt um eins nach hinten. Weggelassen = ans Ende. Overrides, die eine Stufe per escalationTierOrder treffen, behalten ihre Nummer, wie beim Neu ordnen.
autoEscalationEnabled, autoEscalationAfterMinutes, autoEscalationStopMode, autoEscalationSeverities, autoEscalationTimeFilters, repeats, repeatsAfterMinutes, repeatsStopModesiehe StufenfelderNeinDie Einstellungen der Stufe. Weggelassen = Standardwert.

Beispiel (cURL)

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"],
    "autoEscalationAfterMinutes": 10,
    "repeats": 1
  }'

Antwort (Response)

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

{
  "id": 22,
  "tierOrder": 2,
  "autoEscalationEnabled": true,
  "autoEscalationAfterMinutes": 10,
  "autoEscalationStopMode": "acknowledged",
  "autoEscalationSeverities": null,
  "autoEscalationTimeFilters": [],
  "repeats": 1,
  "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 außer tierOrder ist optional und änderbar. Nur die im Body vorhandenen Felder ändern sich.

Beispiel (cURL)

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 schließt du die Lücke, falls du fortlaufende Nummern brauchst.

Beispiel (cURL)

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

Antwort (Response)

200 OK

{ "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)

FeldTypErforderlichBeschreibung
tierIdsnumber[]JaJede Stufen-ID dieses Teams genau einmal, in der neuen Reihenfolge.

Beispiel (cURL)

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

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

Schedule zu einer Stufe hinzufügen

POST /api/im/tiers/:tierId/schedules

Das Team ergibt sich aus der Stufe. Eine unbekannte Stufe oder eine einer anderen Organisation antwortet 404 imEscalationTierNotFound. Der verschachtelte Pfad POST /api/im/teams/:id/tiers/:tierId/schedules nimmt denselben Body und liefert dieselbe Antwort; er ist veraltet und entfällt am 18.01.2027.

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)

FeldTypErforderlichBeschreibung
namestringJa1 bis 120 Zeichen nach dem Trimmen.
timezonestringJaIANA-Zone, in der der Schedule ausgewertet wird.
effectiveFromstring | nullNeinISO-Zeitstempel, vor dem der Schedule niemanden alarmiert.
effectiveUntilstring | nullNeinISO-Zeitstempel, nach dem der Schedule niemanden alarmiert.
weeklySchedulesarrayNeinBereitschaftsfenster, gleiche Form wie autoEscalationTimeFilters. Weggelassen oder [] = 24/7.
rotationsarrayNeinRotationsgruppen, 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. Weggelassene Kadenzfelder stehen auf rotationMode: "none", roundRobinSize: 1, alles andere null. Die resultierende Kadenz wird als Ganzes validiert.

Beispiel (cURL)

curl -X POST "$BASE_URL/api/im/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).

Eskalationskette testen (Probelauf)

POST /api/im/teams/:id/escalation-dry-run

Geht die Stufen des Teams so durch, wie es die Eskalations-Engine für einen Incident mit dem angegebenen Schweregrad zum angegebenen Zeitpunkt tun würde, und meldet pro Stufe, wer wann über welchen Kanal alarmiert würde und was einen Kanal daran hindern würde, jemanden zu erreichen. Es wird nichts gesendet, nichts gespeichert, kein Incident angelegt und Round Robin nicht weitergeschaltet: Eine Round-Robin-Stufe zeigt als Vorschau, wen der nächste Incident vom aktuellen Stand aus bekäme.

Wer ihn aufrufen darf: Organisationsrolle admin oder editor, oder Team-Admin dieses Teams. Alle anderen bekommen 403 imTeamWriteDenied.

Anfrage (Request Body)

Der Body ist optional; {} oder kein Body läuft mit den Standardwerten.

FeldTypErforderlichBeschreibung
atstringNeinISO-8601-Zeitstempel mit Offset: wann der gedachte Incident eintrifft. Standard: jetzt.
severitystringNeinsev1, sev2, sev3 oder sev4. Standard sev1. Wählt bei jeder Person die Regelkette high (sev1/sev2) oder low (sev3/sev4).

Beispiel (cURL)

curl -X POST "$BASE_URL/api/im/teams/3/escalation-dry-run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "at": "2026-10-28T23:00:00+01:00", "severity": "sev1" }'

Antwort (Response)

200 OK

{
  "at": "2026-10-28T22:00:00.000Z",
  "severity": "sev1",
  "urgency": "high",
  "tiers": [
    {
      "tierId": 21,
      "tierOrder": 1,
      "offsetMinutes": 0,
      "repeatOffsetsMinutes": [10],
      "status": "pages",
      "filledFromTier": null,
      "conditionFailedOpen": false,
      "targets": [
        {
          "userId": "u_abc123",
          "name": "Ada Lovelace",
          "channels": [
            { "channel": "push", "delayMinutes": 0, "warnings": [] },
            { "channel": "sms", "delayMinutes": 5, "warnings": ["phoneUnverified"] }
          ],
          "warnings": []
        }
      ]
    },
    {
      "tierId": 22,
      "tierOrder": 2,
      "offsetMinutes": 20,
      "repeatOffsetsMinutes": [],
      "status": "pages",
      "filledFromTier": null,
      "conditionFailedOpen": false,
      "targets": [
        {
          "userId": "u_def456",
          "name": "Bob Fixit",
          "channels": [],
          "warnings": ["noRules"]
        }
      ]
    },
    {
      "tierId": 23,
      "tierOrder": 3,
      "offsetMinutes": null,
      "repeatOffsetsMinutes": [],
      "status": "notReached",
      "filledFromTier": null,
      "conditionFailedOpen": false,
      "targets": []
    }
  ]
}
FeldBeschreibung
at, severityDie Werte, mit denen der Probelauf gerechnet hat.
urgencyhigh bei sev1/sev2, low bei sev3/sev4.
tiers[].offsetMinutesMinuten nach Eintreffen des Incidents, zu denen diese Stufe alarmiert. null, wenn die Stufe übersprungen wird, leer ist oder nicht erreicht wird.
tiers[].repeatOffsetsMinutesMinuten nach Eintreffen des Incidents für jede Wiederholung dieser Stufe.
tiers[].statuspages: Die Stufe alarmiert ihre eigenen Diensthabenden. filledUp: Die Stufe ist leer und leiht sich die Personen der nächsthöheren Stufe, in der jemand Bereitschaft hat (automatisches Auffüllen). skipped: Schweregradfilter oder Zeitfenster der Stufe schließen diesen Incident aus. empty: Niemand hat Bereitschaft und nichts füllt die Lücke. notReached: Eine frühere Stufe beendet die Kette.
tiers[].filledFromTierBei filledUp: die tierOrder der Stufe, deren Personen die Lücke füllen, sonst null.
tiers[].conditionFailedOpentrue, wenn das Zeitfenster der Stufe nicht gelesen werden konnte und die Stufe deshalb trotzdem alarmiert (wie die Engine).
tiers[].targets[]Die Personen, die alarmiert würden: userId, name, ihre channels und warnings.
targets[].channels[]Ein Eintrag pro Regel in der Kette der Person: channel (push, sms, voice, email), delayMinutes (Minuten, nachdem die Stufe alarmiert) und warnings (leer = dieser Kanal käme an).

Mögliche Warnungen:

  • noRules (an der Person): Die Person hat keine Regel für diese Dringlichkeit, über sie wird also niemand alarmiert.
  • phoneUnverified: SMS oder Anruf, und die Person hat keine bestätigte Telefonnummer.
  • noDevice: eine Push-Regel, aber kein registriertes Gerät.
  • quotaExhausted: SMS oder Anruf, und das Telco-Kontingent der Organisation ist aufgebraucht, ohne dass Mehrverbrauch erlaubt ist.
  • disabledForSeverity: Die Person hat diesen Kanal für diesen Schweregrad abgeschaltet.

Zeitablauf wie in der Engine: Eine Stufe alarmiert, wiederholt repeats-mal alle repeatsAfterMinutes (sonst autoEscalationAfterMinutes), dann alarmiert die nächste Stufe autoEscalationAfterMinutes später. Eine übersprungene und eine leere Stufe kosten keine Zeit. Eine Endstufe (die letzte oder eine mit autoEscalationEnabled: false) beendet die Kette; jede spätere Stufe ist notReached. Die Wiederholung der ganzen Kette am Team (Team ändern) ist nicht Teil des Probelaufs.

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; beim Probelauf, wenn du weder Organisations-Admin oder -Editor 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, at beim Probelauf kein ISO-8601-Zeitstempel mit Offset ist oder severity nicht sev1 bis sev4, 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, rotations fehlerhaft ist, oder tierOrder keine Ganzzahl ab 1 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, oder tierOrder größer als die höchste Stufe + 1 ist
  • 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 oder verschoben wurden; erneut versuchen

Auf dieser Seite