Incidents auflisten

GET /api/im/incidents

Liefert eine gefilterte Liste der Incidents deiner Organisation, neueste zuerst (triggeredAt absteigend, dann id absteigend). Jeder Eintrag trägt die Felder des Incidents selbst und dazu eine kleine, seitenweit aufgelöste Ergänzung: die primäre Zuweisung, die Personen hinter den Lebenszyklus-Spalten und die Alert-Aktivität des Incidents (siehe Aufgelöste Personen weiter unten). Die vollständigen Alerts, Timeline-Events und Zuweisungen eines Incidents liefert der Endpunkt Incident abrufen.

AuthentifizierungAnkerlink kopieren

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

Query-ParameterAnkerlink kopieren

Ein wiederholbarer Parameter akzeptiert einen wiederholten Query-Key, z. B. status=triggered&status=acknowledged. Bei Einzelwert-Parametern gilt das letzte Vorkommen.

Beispiel (cURL)Ankerlink kopieren

Cursor-Modus:

curl -X GET "$BASE_URL/api/im/incidents?status=triggered&status=acknowledged&severity=sev1&limit=25&envelope=items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Seiten-Modus, zweite Seite mit eingefrorener Ergebnismenge:

curl -X GET "$BASE_URL/api/im/incidents?page=2&limit=25&asOf=2026-07-17T10:00:00.000Z&envelope=items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Antwort (Response)Ankerlink kopieren

{
  "items": [
    {
      "id": 42,
      "organizationId": 1,
      "teamId": 3,
      "title": "Database connection pool exhausted",
      "customerId": null,
      "primarySourceId": 7,
      "severity": "sev1",
      "severityManual": false,
      "status": "acknowledged",
      "mergedIntoId": null,
      "escalationPolicyId": null,
      "currentTier": null,
      "escalationEpoch": 1,
      "escalationCycle": 0,
      "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo",
      "acknowledgedAt": "2026-07-17T09:15:31.000Z",
      "snoozedUntil": null,
      "autoResolve": true,
      "resolvedBy": null,
      "resolveNote": null,
      "statuspageUpdate": null,
      "createdBy": null,
      "sourceKind": "alert",
      "isTest": false,
      "category": null,
      "isNearMiss": false,
      "triggeredAt": "2026-07-17T09:12:00.000Z",
      "resolvedAt": null,
      "serviceId": 4,
      "assignee": {
        "userId": "MFcTjWmYq2LpzR8vK1sXo",
        "name": "Grace Hopper",
        "role": "commander",
        "image": "/api/assets/avatar/MFcTjWmYq2LpzR8vK1sXo"
      },
      "createdByUser": null,
      "acknowledgedByUser": {
        "userId": "MFcTjWmYq2LpzR8vK1sXo",
        "name": "Grace Hopper",
        "image": "/api/assets/avatar/MFcTjWmYq2LpzR8vK1sXo"
      },
      "resolvedByUser": null,
      "lastAlertAt": "2026-07-17T09:41:00.000Z",
      "alertDuplicateCount": 3,
      "host": "db-2.example.com:5432"
    }
  ],
  "nextCursor": "1752743520000:42",
  "hasMore": true
}

nextCursor ist null auf der letzten Seite. Im Cursor-Modus übergibst du ihn als cursor-Query-Parameter, um die nächste Seite zu laden.

Im Seiten-Modus (page gesetzt) enthält die Antwort zusätzlich total (Anzahl der Incidents, die alle Filter und asOf erfüllen) und asOf (den eingefrorenen Stichzeitpunkt als ISO 8601). Ohne page fehlen beide Felder.

Listenform: Mit envelope=items trägt jede Antwort zusätzlich hasMore (false auf der letzten Seite), und der Seiten-Modus ergänzt page und perPage (das wirksame limit) neben total und asOf. Ohne den Parameter antwortet der Endpunkt noch in der bisherigen Form ({ items, nextCursor }, im Seiten-Modus zusätzlich total und asOf); sie ist veraltet, ab dem 18.01.2027 ist die Listenform der Standard.

lastAlertAt ist das jüngste alertbezogene Timeline-Event des Incidents (null, wenn es keines gibt), alertDuplicateCount die Zahl der Wiederholungen, die seine Alerts per Deduplizierung aufgefangen haben. Beides steht in keiner Incident-Spalte und wird deshalb getrennt ausgewiesen.

host nennt das System, um das es geht: den host des jüngsten Alerts, der einen trug (die URL einer Website, hostname:port eines Server-Monitors, eine Domain, ein Zabbix-Host). null, wenn kein Alert einen nannte, etwa bei einem manuell angelegten Incident.

Zu den Feldern: sourceKind ist alert, manual oder api. isTest markiert einen Incident, der von einer Testseite ausgelöst wurde. category (availability, security, other oder null) und isNearMiss sind die NIS-2-Einstufung, siehe Incident einstufen. escalationPolicyId wird nicht mehr verwendet und ist bei neuen Incidents immer null; die Eskalationskette ergibt sich aus den Eskalations-Tiers des Teams.

Aufgelöste PersonenAnkerlink kopieren

assignee ist die primäre Rolleninhaberin des Incidents (commander vor tech_lead vor comms vor assignee) oder null, wenn niemand eine Rolle darin hält.

createdByUser, acknowledgedByUser und resolvedByUser sind die Personen hinter den Benutzer-IDs in createdBy, acknowledgedBy und resolvedBy derselben Zeile. Jedes Feld ist null, wenn die zugehörige ID null ist.

Alle diese Angaben löst der Server in einer einzigen gebündelten, auf deine Organisation eingegrenzten Abfrage für die gesamte Seite auf:

• name ist der Anzeigename der Person. Nur Organisations-Admins (und damit ein normaler organisationsweiter API-Token) bekommen ersatzweise die E-Mail-Adresse, wenn im Profil kein Name hinterlegt ist; für jede andere Rolle steht dann null.
• name ist null, wenn die ID zu einer Person außerhalb deiner Organisation gehört, etwa zu einer organisationsübergreifend handelnden Plattform-Administration oder zu einem inzwischen gelöschten Konto. Zeige dafür einen neutralen Platzhalter an. Die API gibt bewusst keinen Namen heraus, den du nicht sehen darfst, und die rohe Benutzer-ID ist keine Beschriftung.
• image ist die Auslieferungs-URL des Profilbilds oder null, wenn die Person keines hat. Es ist ein autorisierender Pfad dieser API und keine öffentliche Bucket-URL, muss also mit denselben Zugangsdaten abgerufen werden.

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized wenn du nicht authentifiziert bist
• 403 Forbidden (customerScopedTokenForbidden) bei Verwendung eines kunden-gescopten Tokens
• 403 Forbidden (imAccessDenied) wenn die angemeldete Person keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 400 Bad Request (invalidRequestBody) wenn ein Filterwert ungültig ist: ein unbekannter status/severity/category, ein teamId/customerId/sourceId/serviceId, der keine positive Ganzzahl ist, ein nicht parsbarer from/to/asOf/cursor, ein limit oder page unter 1, oder page und cursor zusammen