Incident abrufen

GET /api/im/incidents/:id

Liefert die vollständigen Details eines einzelnen Incidents: den Incident-Datensatz sowie seine Alerts (eine sichere, geschwärzte Sicht, siehe unten), Timeline-Events in chronologischer Reihenfolge und Rollen-Zuweisungen.

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.

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/incidents/42" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Antwort (Response)Ankerlink kopieren

{
  "id": 42,
  "organizationId": 1,
  "teamId": 3,
  "title": "Database connection pool exhausted",
  "customerId": null,
  "primarySourceId": 7,
  "severity": "sev1",
  "severityManual": false,
  "status": "triggered",
  "mergedIntoId": null,
  "escalationPolicyId": null,
  "currentTier": 1,
  "escalationEpoch": 0,
  "escalationCycle": 0,
  "acknowledgedBy": null,
  "acknowledgedAt": null,
  "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": null,
  "statuspageRuleApplies": false,
  "customerName": null,
  "customerPublicId": null,
  "monitoringIncidentPublicId": null,
  "hasReportCase": false,
  "reportCasePublicId": null,
  "postmortemStatus": "none",
  "needsPostmortem": false,
  "canManagePostmortem": false,
  "mergeSuggestions": [
    {
      "incidentId": 41,
      "title": "db-primary-01 unreachable",
      "reason": "host",
      "suggestedAt": "2026-07-17T09:12:01.000Z"
    }
  ],
  "alerts": [
    {
      "id": 101,
      "organizationId": 1,
      "sourceId": 7,
      "dedupKey": "db-primary-01:pool-exhausted",
      "status": "open",
      "suppressedReason": null,
      "title": "Database connection pool exhausted",
      "severity": "sev1",
      "host": "db-primary-01",
      "mappedFields": {},
      "duplicateCount": 0,
      "firstSeenAt": "2026-07-17T09:12:00.000Z",
      "resolvedAt": null,
      "incidentId": 42
    }
  ],
  "events": [
    {
      "id": 501,
      "incidentId": 42,
      "at": "2026-07-17T09:12:00.000Z",
      "kind": "alert_received",
      "actorUserId": null,
      "actorName": null,
      "payload": {}
    },
    {
      "id": 502,
      "incidentId": 42,
      "at": "2026-07-17T09:15:00.000Z",
      "kind": "acknowledged",
      "actorUserId": "u_abc123",
      "actorName": "Jane Doe",
      "payload": {}
    }
  ],
  "assignments": [
    {
      "id": 12,
      "userId": "u_abc123",
      "userName": "Jane Doe",
      "role": "commander",
      "createdAt": "2026-07-17T09:15:00.000Z"
    }
  ],
  "publicUpdates": [
    {
      "id": 17,
      "publicId": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
      "status": "investigating",
      "body": "We are investigating slow logins.",
      "createdAt": "2026-07-17T09:20:00.000Z",
      "createdByUserId": "u_abc123"
    }
  ]
}

publicUpdates ist die öffentliche Timeline des Incidents, älteste zuerst und append-only: ein Eintrag je Text, der über Statusseiten-Text aktualisieren gesetzt wurde, jeweils mit status (investigating, identified, monitoring, resolved), body, createdAt und createdByUserId (null, sobald die Person gelöscht ist). Öffentliche Statusseiten zeigen sie ohne die Person.

statuspageRuleApplies ist true, wenn eine Statusseiten-Regel des Teams für diesen Incident eine Statusseite umschalten würde (eine Regel für sein Team, deren Mindestschwere er erreicht). statuspageUpdate ist der kuratierte Text, der dort erscheint (setzen mit Statusseiten-Text aktualisieren).

customerName und customerPublicId benennen den Kunden aus customerId; beide sind null, wenn der Incident keinem Kunden zugeordnet ist.

monitoringIncidentPublicId ist die öffentliche ID des Uptimeify-Monitoring-Vorfalls, aus dem dieser Incident über die Monitoring-Bridge entstand (Quelltyp uptimeify_monitoring), etwa für einen Link auf /dashboard/system/incidents/<publicId>. Bei jeder anderen Quelle ist das Feld null.

mergeSuggestions listet offene Incidents aus ANDEREN Alert-Quellen deiner Organisation, die vermutlich derselbe Vorfall sind: höchstens 15 Minuten von diesem entfernt ausgelöst und entweder demselben Dienst zugeordnet (reason: "service", bevorzugt) oder mit einem offenen Alert auf demselben Host (reason: "host"; Hosts werden ohne Schema, Port, Pfad, abschließenden Punkt und Groß-/Kleinschreibung verglichen, db-01:9100 und https://DB-01/ treffen sich also). Der Vorschlag entsteht einmal, beim Anlegen dieses Incidents, höchstens drei davon, und zusammengeführt wird nie automatisch: zusammenführen mit Incidents zusammenführen (dieser Incident in incidentId) oder verwerfen mit Vorschlag zum Zusammenführen verwerfen. Die Liste ist leer, sobald dieser Incident gelöst oder zusammengeführt ist, und ein Vorschlag mit geschlossenem Ziel fällt weg. In der Timeline ist der Vorschlag das Ereignis merge_suggested ({ targetIncidentId, targetTitle, reason, host? }), das Verwerfen merge_suggestion_dismissed ({ targetIncidentId }). Ein Vorschlag löst keine Benachrichtigung aus.

hasReportCase ist true, wenn der Incident mit einem NIS-2-Meldefall verknüpft ist. Dessen Inhalt sehen nur Admins und Meldeverantwortliche.

reportCasePublicId ist die publicId dieses Meldefalls, für einen Link dorthin. Nur Organisations-Admins und Meldeverantwortliche mit Sitzung bekommen sie; für alle anderen und ohne verknüpften Fall ist sie null.

category ist die NIS-2-Vorfallkategorie (availability, security, other oder null, solange nicht eingestuft), isNearMiss markiert einen Beinahevorfall; beides setzt Incident einstufen. postmortemStatus ist none, draft oder completed (siehe Postmortem). needsPostmortem ist true, wenn NIS-2 eingeschaltet ist, der Incident ein Postmortem braucht und noch keins abgeschlossen ist. canManagePostmortem ist true für Organisations-Admins und Meldeverantwortliche mit Sitzung.

events[].actorName ist der Anzeigename der Person hinter events[].actorUserId, serverseitig aufgelöst, damit du ihn nicht selbst nachschlagen musst. Bei einem Systemereignis, also einem Ereignis ohne handelnde Person (ein eingehender Alert, eine feuernde Eskalationsstufe), steht dort null. Ebenfalls null steht dort, wenn sich die Person innerhalb der Organisation des Incidents nicht benennen lässt, etwa bei einem Plattform-Operator oder einem gelöschten Konto. Stelle in diesem Fall eine anonyme Akteurin dar: die Kennung in actorUserId ist ein interner Bezeichner und keine Beschriftung. Eine Person ohne Anzeigenamen wird nur für Organisations-Admins mit ihrer E-Mail-Adresse beschriftet; jede andere Rolle bekommt auch dann null.

Die beiden Eskalationsereignisse tragen payload.toTargetName, den Namen dessen, was der Tier im Moment der Eskalation alarmiert: der erste Schedule des Tiers, bei einem Tier ohne Schedule der Name des Teams (null, wenn es beides nicht gibt). escalated (ein manuelles Sofort eskalieren) hat { fromTier, toTier, toTargetName }, escalated_tier (ein Tier, der von selbst feuert) hat { tier, repeat, userIds, toTargetName }. Ereignisse von vor diesem Feld haben es nicht.

alerts[].rawPayload wird von diesem Endpunkt nie zurückgegeben: das rohe Webhook-/API-Payload kann API-Keys oder andere Secrets enthalten, die der Betreiber der Source darin platziert hat. Es wird außerdem serverseitig 90 Tage nach dem Eingang durch einen Retention-Job genullt. alerts[].mappedFields ist die bereits normalisierte, sichere Sicht auf denselben Alert und übersteht die Retention. Sie trägt die url des Alerts (den Link zurück zum Ursprung: den Monitor im Dashboard, das Zabbix-Event, das Grafana-Panel), sofern die Source eine lieferte, und jedes gemappte Custom-Feld als flachen String-Schlüssel daneben (bei der Monitoring-Bridge etwa monitor_type, region, failed_locations, last_success_at). Der reservierte Schlüssel _mapping enthält Anzeige-Metadaten, kein Feld.

Retention im Detail: Alert-Payloads (rawPayload) werden 90 Tage nach dem Eingang genullt; aufgelöste (resolved) Alerts werden 90 Tage nach dem Eingang gelöscht; Outbound-Delivery-Datensätze (Integrations-Weiterleitung) werden 90 Tage nach dem Versand gelöscht. Der Vorfall selbst und seine Zeitleisten-Ereignisse (events) bleiben 12 Monate nach Auslösung vollständig erhalten; danach überlebt nur noch ein Tagesaggregat (Vorfallzahlen sowie Quittier- und Auflösezeiten je Team und Schweregrad), insgesamt 24 Monate. Die täglichen Aggregate pro Source (Alert-/Dedup-/Incident-Zähler, wie im Analytics-Tab einer Source angezeigt) werden unbegrenzt aufbewahrt. Das Löschen der zugrunde liegenden Alert-Zeilen löscht diese Historie nicht mit.

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 :id keine positive Ganzzahl ist
• 404 Not Found (imIncidentNotFound) wenn der Incident nicht existiert oder zu einer anderen Organisation gehört