Incident reference

The full request schemas live in the auto-generated API Reference. This page is the human-readable cheat sheet.

Incident object

Field	Type	Description
id	uuid	Incident ID.
title	string	Short, scannable label.
severity	enum	minor, major, or critical.
status	enum	Customer-facing progress. See status enum.
responder_status	enum	Internal responder state. See responder status.
status_page_ids	uuid[]	Every status page the incident is published on.
status_page_id	uuid | null	Deprecated: the page it was created on. Use status_page_ids.
public_title	string | null	The title status pages show. null shows title.
service_id	uuid | null	Optional service tag.
monitors	object[]	The monitors this incident is about (below). Empty in list responses.
affected_http_job_ids	uuid[]	Deprecated: the http monitors in monitors.
participants	object[]	The people working the incident (below). Empty in list responses.
merged_into_id	uuid | null	Set on an incident that was merged into another.
resolution_reason	string | null	merged for an incident that was merged into another, otherwise null.
merged_from	object[]	The incidents merged into this one: id, title, created_at and their own updates. Updates stay on the source incident. Empty in list responses.
acknowledged_at	rfc3339 | null	When a responder acknowledged.
acknowledged_by	uuid | null	Who acknowledged.
resolved_at	rfc3339 | null	When the incident resolved.
unassigned_after_exhaustion	bool	true while nobody has acknowledged and the service’s escalation policy ran out, so nobody owns the incident. Always false in list responses.
auto_created	bool	true when a monitor state change opened the incident; false for manual ones.
created_at	rfc3339	When the incident opened.
updates	object[]	Chronological incident updates (below).

Incident update

Field	Type	Description
id	uuid	Update ID.
status	enum	The public status when it was posted.
message	string	Written update text.
visibility	enum	public shows on status pages; internal shows only in the app.
author_user_id	uuid | null	Who posted it. null for the system, API keys and updates from before October 2026.
created_at	rfc3339	When posted.

Incident monitor

Field	Type	Description
monitor_id	uuid	The monitor.
monitor_type	enum	http, cron, browser, tls, dns, dns_record, page_speed or alert_rule.
name	string | null	The monitor’s name.
impact	enum | null	degraded, partial_outage or major_outage. null derives it from the incident’s severity.
source	enum	auto (joined because it failed) or manual (added by someone).
joined_at	rfc3339	When the monitor joined the incident.
recovered_at	rfc3339 | null	When the monitor recovered.

See affected monitors and impact.

Incident participant

Field	Type	Description
user_id	uuid	The user. Participants must be users in your account.
role	enum	lead, responder or comms. At most one lead.
added_by	uuid | null	Who added them.
added_at	rfc3339	When they were added.
paged_at	rfc3339 | null	When they were paged for this incident, or null.

See participants.

Postmortem

Field	Type	Description
id	uuid	Postmortem ID.
incident_id	uuid	The incident. An incident has at most one postmortem.
status	enum	draft, in_review or published. Publishing needs a resolved incident.
body	string	Markdown, up to 100,000 characters. Drafted from the timeline when started without one.
owner_user_id	uuid | null	The user who drives it.
created_by_user_id	uuid | null	Who started it.
created_at / updated_at	rfc3339	When it was started and last changed.
published_at	rfc3339 | null	When it was last moved to published.

Action item

Field	Type	Description
id	uuid	Action item ID.
incident_id	uuid	The incident it follows up.
title	string	Up to 300 characters.
status	enum	open, done or wont_do.
owner_user_id	uuid | null	The user who owns it.
due_date	date | null	YYYY-MM-DD.
external_url	string | null	An http or https link to the tracking issue.
created_by_user_id	uuid | null	Who added it.
created_at / updated_at	rfc3339	When it was added and last changed.
completed_at	rfc3339 | null	When it left open; cleared when reopened.
overdue	bool	true for an open item past its due date in the organization’s timezone.
reminded_at	rfc3339 | null	When the owner was emailed that it is overdue.
incident	object	On the follow-up list only: the incident’s id, title, severity and responder_status.

See postmortems and follow-ups.

Public and internal updates

A public update shows on every status page the incident is published on and can move its status. An internal note stays in the app: it never reaches a status page or its subscribers, and it never changes status. Status pages show the public_title (or title when it is empty) and public updates only.

Account members with incident write access can edit or delete an internal note from its timeline entry, including after resolution. Public updates stay in the timeline; post a correction instead. Notes on merged source incidents are read-only.

PUT /incident/{incident_id}/update/{update_id} accepts only { "message": "Updated note" } and returns the note. It preserves the original author and posting time. Empty messages return 400. DELETE at the same path returns 204 with no body. Either route returns 404 for a missing, foreign or public update, 403 without incident write access, and 409 for a merged incident. These actions do not change incident status or notify subscribers. The timeline event records who edited or deleted the note.

Resolving a published incident always posts a public resolved update. The text is the one you give, else the service’s public template, else “This incident has been resolved.”

Status enum

Value	Meaning
investigating	Cause not yet known.
identified	Cause known, fix in progress.
monitoring	Fix rolled out, watching.
resolved	Done. The only non-active status.

Responder status enum

Value	Meaning
triggered	No one has claimed the incident. Escalation keeps paging.
acknowledged	A responder owns it. Escalation stops.
resolved	Responder work is done.

Request bodies

Create (POST /incident or POST /status_page/{id}/incident)

Field	Type	Required	Description
title	string	yes	Incident title.
severity	enum	without service_id	minor / major / critical. Defaults to the service’s default severity.
message	string	yes	Text of the first incident update.
status_page_id	uuid	no	Publish to a status page at creation.
monitors	object[]	no	Affected monitors: { "monitor_id", "monitor_type", "impact" }, with impact optional.
affected_http_job_ids	uuid[]	no	Deprecated: affected HTTP monitors. Use monitors. Sending both is fine, and duplicates are accepted.
service_id	uuid	no	Service tag.

Update (PUT /incident/{incident_id})

Every field is optional. Send only what changes:

Field	Type	Description
title	string	New title.
severity	enum	New severity. Raising it from minor to major or critical pages the current escalation level again, and an acknowledged incident goes back to triggered.
service_id	uuid | null	Move the incident to this service (404 if it is not in your account). null detaches it. Leaving it out keeps the current service. Moving an open incident cancels the old service’s escalation and starts the new service’s policy at level one, only while the incident is triggered.
status	enum	Deprecated: post an update, or resolve. resolved resolves the incident with a public update; another value sets the status.
resolved_at	rfc3339	Deprecated and ignored: resolving records the time.
public_title	string | null	The title status pages show, up to 512 characters (400 if longer). null or blank clears it.

Post an update (POST /incident/{incident_id}/update)

Field	Type	Description
message	string	Update text.
visibility	enum	public (default) or internal.
status	enum	Optional, public updates only. The new status; leaving it out keeps the current one. resolved resolves the incident, and a status earlier than the current one returns 409 unless force is true. On an internal note it is ignored, and resolved returns 400.
force	bool	Allow a public update to move the status backward.
notify_subscribers	bool	Email the subscribers of every status page the incident is on about a public update. Default false here, and true on POST /status_page/{status_page_id}/incident/{incident_id}/update, which emails only that page.

Acknowledge (POST /incident/{incident_id}/acknowledge)

Field	Type	Description
acknowledged_by	uuid	Required with an API key or API client: a user in your account. A signed-in user always acknowledges as themselves.

Resolve (POST /incident/{incident_id}/resolve)

Every field is optional:

Field	Type	Description
message	string	Text of the public resolved update.
post_public_update	bool	Post that update even when the incident is on no status page. A published incident always gets one.
notify_subscribers	bool	Email the subscribers of every page the incident is on. Default true.

Merge (POST /incident/{incident_id}/merge)

{incident_id} is the target. See merge incidents.

Field	Type	Required	Description
source_ids	uuid[]	yes	The incidents to merge into the target, 1 to 20.

Returns the target incident. 400 for an empty list or more than 20 ids, and 404 when the target or any source is not in your account. A merge is all or nothing: a 409 changes nothing, and its data.incident_id names the incident it refused.

Participants

Method	Path	Body	Returns
GET	/incident/{incident_id}/participants	none	The participant list.
POST	/incident/{incident_id}/participants	Exactly one of user_id, schedule_id or escalation_policy_id, plus optional role (default responder) and page (default true).	The full participant list.
PUT	/incident/{incident_id}/participants/{user_id}	{ "role": "lead" | "responder" | "comms" }	The full list. Making someone lead demotes the previous lead to responder.
DELETE	/incident/{incident_id}/participants/{user_id}	none	204.

A schedule adds whoever is on call now. A policy adds the users and on-call people at its first level. With page true, each added user is paged through their own notification rules. Paging an incident without a service returns 400, and paging a resolved one returns 409 (resolved); send "page": false there. A lead must be sent as user_id. The first user to acknowledge becomes lead when there is none.

Monitors

Method	Path	Body	Returns
POST	/incident/{incident_id}/monitors	{ "monitor_id", "monitor_type", "impact" }, with impact optional.	The full monitor list. Adding one that is already linked changes nothing and returns 200.
PUT	/incident/{incident_id}/monitors/{monitor_type}/{monitor_id}	{ "impact": null | "degraded" | "partial_outage" | "major_outage" }	The full list.
DELETE	/incident/{incident_id}/monitors/{monitor_type}/{monitor_id}	none	204.

Postmortem

Method	Path	Body	Returns
GET	/incident/{incident_id}/postmortem	none	The postmortem, or 404 when there is none.
POST	/incident/{incident_id}/postmortem	Optional body and owner_user_id. Without body it is drafted from the timeline.	201 and the new draft.
PUT	/incident/{incident_id}/postmortem	Any of body, status, owner_user_id (null clears it).	The postmortem.
DELETE	/incident/{incident_id}/postmortem	none	204. The action items stay.

Action items

Method	Path	Body	Returns
GET	/incident/{incident_id}/action_items	none	The incident’s action items, oldest first.
POST	/incident/{incident_id}/action_items	title, plus optional owner_user_id, due_date and external_url.	201 and the item.
PUT	/incident/{incident_id}/action_items/{action_item_id}	Any of title, status, owner_user_id, due_date, external_url; null clears the last three.	The item.
DELETE	/incident/{incident_id}/action_items/{action_item_id}	none	204.
GET	/incident/action_items	Query: status (open default, done, wont_do, all), owner_user_id, overdue (true for only open items past their due date), limit (default 50, at most 100), offset.	Every incident’s items in data, soonest due first, plus total.

A new due date or owner re-arms the one overdue email. See the reminder.

Publish (POST /incident/{incident_id}/publish)

Field	Type	Description
status_page_id	uuid	The status page to publish this incident to. A page that is not in your account returns 404.
title	string	Optional. Sets public_title. Otherwise the page keeps the current public title, then uses the service template’s title. An incident a monitor opened shows “Service disruption” rather than its monitor’s name.
message	string	Optional. A public update to post with it. When the incident has no public update yet, one is always posted: this text, else the service template’s message, else “We are investigating this issue.”
notify_subscribers	bool	Email the page’s subscribers that the incident opened. Default true. Never sent for a resolved incident, and at most once per page.

Publishing to a page the incident is already on changes nothing unless you send a title or message.

Unpublish (DELETE /incident/{incident_id}/publish/{status_page_id})

Takes the incident off that page. The incident and its updates are kept, and nobody is emailed. Returns the incident, or 404 when it is not on that page.

Incident metrics

GET /incident/metrics returns counts and acknowledgment/resolution durations for incidents created in a time window. It requires read:incidents. The MCP tool is incident_metrics.

Query	Meaning
from	Inclusive creation time, RFC 3339. Defaults to 30 days before to.
to	Exclusive creation time, RFC 3339. Defaults to now. The maximum window is 366 days.
service_id	Only incidents currently associated with this account-owned service. A missing or foreign service returns 404.
severity	Current severity: minor, major or critical.

The response contains total_incidents, open_incidents, resolved_incidents and acknowledged_incidents, plus mtta and mttr. Each duration summary has samples, mean_seconds, p50_seconds and p90_seconds. Percentiles use continuous interpolation. With no samples the durations are null, not zero.

MTTA runs from creation to the first acknowledgment event. MTTR runs from creation to the latest resolution event for incidents currently resolved. Earlier incidents without those events use their stored acknowledgment and resolution times. Unresolved incidents contribute no MTTR sample. Negative durations are excluded. Merged source incidents contribute to neither counts nor durations.

The time window selects creation times; lifecycle state and duration values are current when queried. A resolution after to can therefore contribute, and later service or severity edits can change filtered results. acknowledged_incidents counts incidents with an acknowledgment time, including resolved incidents and incidents triggered again after reopening.

Full incident detail and lifecycle responses can also include first_paged_at, the first responder page accepted by its provider, and mitigated_at, the first public status transition to monitoring. These fields are omitted when no matching event exists and on list responses. Resolution alone does not set a mitigation time.

Endpoints

Standalone incidents:

Method	Path	Purpose
POST	/incident	Create.
GET	/incident	List, with limit / offset pagination.
GET	/incident/metrics	Creation-cohort counts and MTTA/MTTR summaries.
GET	/incident/action_items	The follow-up list: every incident’s action items.
GET / PUT / DELETE	/incident/{incident_id}	Detail / update / delete.
POST	/incident/{incident_id}/acknowledge	Acknowledge (stops escalation).
POST	/incident/{incident_id}/resolve	Resolve.
POST	/incident/{incident_id}/update	Post an incident update.
POST	/incident/{incident_id}/reopen	Reopen a resolved incident.
POST	/incident/{incident_id}/merge	Merge other incidents into this one.
GET / POST	/incident/{incident_id}/participants	List / add participants.
PUT / DELETE	/incident/{incident_id}/participants/{user_id}	Change a participant’s role / remove them.
POST	/incident/{incident_id}/monitors	Add an affected monitor.
PUT / DELETE	/incident/{incident_id}/monitors/{monitor_type}/{monitor_id}	Set a monitor’s impact / remove it.
GET / POST / PUT / DELETE	/incident/{incident_id}/postmortem	Read / start / edit / delete the postmortem.
GET / POST	/incident/{incident_id}/action_items	List / add action items.
PUT / DELETE	/incident/{incident_id}/action_items/{action_item_id}	Edit or close / delete an action item.
POST	/incident/{incident_id}/publish	Publish to a status page.
DELETE	/incident/{incident_id}/publish/{status_page_id}	Unpublish from a status page.
GET / POST	/incident/action/{token}	Acknowledge or resolve from an email or SMS. GET shows a confirmation page and changes nothing; POST (its button) acts. Token-authenticated, no session needed. Each link is made for one paged user, works once, expires after 24 hours, and stops working when the incident changes state.

Status-page-scoped incidents (same shapes, scoped to one page):

Method	Path	Purpose
POST / GET	/status_page/{status_page_id}/incident	Create / list.
GET / PUT / DELETE	/status_page/{status_page_id}/incident/{incident_id}	Detail / update / delete.
POST	/status_page/{status_page_id}/incident/{incident_id}/update	Post an update. A public one emails that page’s subscribers unless notify_subscribers is false.

Conflicts (409)

A 409 from these routes carries a code in data.conflict:

Route	data.conflict	Meaning
POST /incident/{id}/merge	same_incident	A source is the target.
POST /incident/{id}/merge	source_merged	A source was already merged into another incident.
POST /incident/{id}/merge	source_resolved	A source is already resolved.
POST /incident/{id}/merge	target_resolved	The target is resolved.
POST /incident/{id}/merge	target_merged	The target was merged into another incident.
POST /incident/{id}/participants	merged	The incident was merged into another.
POST /incident/{id}/participants	resolved	page is true on a resolved incident.
POST /incident/{id}/participants	nobody_on_call	The schedule or policy resolved to no one.
POST /incident/{id}/monitors	merged	The incident was merged into another.
POST /incident/{id}/postmortem	exists	The incident already has a postmortem; data.postmortem holds it.
POST /incident/{id}/postmortem	merged	The incident was merged into another.
PUT /incident/{id}/postmortem	incident_open	Publishing before the incident is resolved.
POST /incident/{id}/action_items	merged	The incident was merged into another.
PUT /incident/{id}	open_auto_incident_exists	You moved an auto-created incident onto a service that already has an open auto-created incident.
POST /incident/{id}/reopen	open_auto_incident_exists	Another open auto-created incident already covers that service.
POST /incident/{id}/reopen	merged	A merged incident cannot reopen.

See also

• Incidents overview for the lifecycle and the status vs responder-status distinction.
• Escalation policy reference for what triggered sets in motion.
• API Reference for wire-level shapes.
• Manage incidents from the CLI for terminal and CI workflows.