Severity levels
Severity indicates the impact of an incident. Set it when you create the incident and update it if conditions change.Severity is the single dial scaling.cloud uses to rank incident impact — there is no
separate “priority” field. If you ingest CloudWatch
alarms,
the
[P1]–[P4] markers in an alarm description are just shorthand for these
severity levels ([P1] → critical, through [P4] → low), not a distinct
priority scale.Status lifecycle
Every incident starts atinvestigating and moves forward through four statuses. Transitions are one-way — you cannot skip a step or go back to a previous status.
Incident Updates
An Incident Update is the single unit of timeline activity on an incident. Every update carries:
At least one of
body or statusChange must be present. A public update always requires a non-empty body.
This single concept replaces what used to be two separate things: free-form internal notes, and the implicit “row written every time you transitioned status.” Today, both flow through the same shape — the difference is whether body, statusChange, or both are set.
Visibility — internal vs public
Every input surface (web, Slack, MCP, public API) defaults to
internal. Publishing is always an explicit, deliberate action — you cannot publish by accident.
Publishing requires a covering Status Page
Posting apublic update is rejected with NO_PUBLIC_SURFACE (400) unless your org has at least one published Status Page whose selected components overlap with the incident’s affected components. This is enforced server-side before any write.
This prevents the silent-failure case where you publish into the void — i.e., write a public message that no surface actually renders. Configure your Status Page to include the affected components before publishing. See Status pages for component selection.
Redacting a published mistake
Updates are append-only. To correct or remove a previous statement, redact it and post a new one — the system never silently edits a customer-visible record.
Redaction wipes the
body, sets redactedAt and redactedBy, and preserves any statusChange the update carried — the system does not lie about lifecycle state. On the public status page, the slot remains visible at its original timestamp, rendered as “This update has been removed.” The original wording is gone, but the fact that something existed and was pulled back is visible.
Redaction is permitted even on resolved incidents — it is the only mutation that survives the terminal status.
Origin — human vs system
Not every action on an incident is taken by a person. An incident can be auto-opened from an ingested alert, an update can be an auto-resolution posted when the upstream alert clears, and a provisional status page can be promoted automatically. To keep the timeline honest about who did what, both incidents and Incident Updates carry an origin:origin is the truth-bearing field for attribution. A createdBy / postedBy user is still recorded on every incident and update for audit and plumbing, but a system origin means that user is the integration’s owner, not someone who personally acted.
System-origin actions render without human attribution:
- On the internal timeline, a system-origin update is attributed to Automated instead of a member’s name.
- On a public status page, a system-origin entry carries an Automated badge — so customers see that an auto-resolution was the platform, not a named engineer “resolving” what an alarm resolved.
origin (human or system) is exposed on incident and Incident Update payloads in the API — see Get Incident and List Incident Updates. It also powers the longest silence and time to mobilize metrics in Insights.
Status history and audit trail
The incident detail view shows the full ordered timeline of updates: internal notes, public messages, and status transitions interleaved at their actual post times. Each entry records who posted it, when, and (for redacted updates) who redacted it and when. System-origin entries show Automated in place of a member’s name — see Origin. The legacystatusHistory field on the Get Incident response remains populated for backwards compatibility — it surfaces just the status transitions. For the full timeline (notes + transitions + public updates), call List Incident Updates.
Creating an incident
When you create an incident, the following fields are available:At least one of
leadId or leadScheduleId is required so the paging path
always has a target.Assigning an on-call lead
PassleadScheduleId at creation time to hand the incident to the team that is currently on-call. The server resolves the lead and escalation in one step:
- It looks up the current on-call responder for the schedule (including active overrides) and sets them as the incident lead.
- It searches your escalation policies for one whose layers target that schedule, and attaches the match.
leadId, that user wins as the incident lead — the schedule is still used to find a matching escalation policy. If no one is currently on-call and no leadId was supplied, the incident is still created without a lead; you can assign one later from the incident detail page.