Acknowledge / Update Incident Status

Two endpoints change an open incident's status:

• Acknowledge is the idempotent "I have got this" call. It acts on any open incident that has not been acknowledged yet and is open to everyone with IM access, because an acknowledgement only ever stops paging.
• Change status moves an incident between the open statuses, including acknowledged. It is restricted to the incident's team.

Neither endpoint can reach resolved (use Resolve Incident) or merged (use Merge Incidents).

What an acknowledgement stops depends on the incident's current escalation tier. By default it stops the whole escalation chain. If that tier is configured to stop escalating only on resolve, an acknowledgement silences the current page but further tiers keep escalating until the incident is resolved.

AuthenticationCopy Anchor Link

Any IM-eligible role (admin, editor, responder) or an organization-wide API token, see Authentication. Incident Management must be enabled for the organization.

AcknowledgeCopy Anchor Link

POST /api/im/incidents/:id/ack

Acknowledges an open incident that has no acknowledgement yet (acknowledgedAt is null). A triggered incident moves to acknowledged. An incident that was moved to investigating, identified or monitoring without an acknowledgement keeps its status, but the acknowledgement is recorded (acknowledgedBy, acknowledgedAt) and escalation stops exactly as for a triggered one; status in the response is that unchanged status. Calling it again, or calling it on a resolved or merged incident, is not an error: the response says alreadyAcknowledged: true and reports the current status. The timeline records the acknowledgement with source: "api" for an API token and source: "ui" for a browser session.

No request body.

Example (cURL)Copy Anchor Link

curl -X POST "$BASE_URL/api/im/incidents/42/ack" \
  -H "Authorization: Bearer $TOKEN"

ResponseCopy Anchor Link

200 OK, first acknowledgement:

{
  "acknowledged": true,
  "alreadyAcknowledged": false,
  "status": "acknowledged",
  "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo",
  "acknowledgedAt": "2026-07-17T09:20:00.000Z"
}

Both responses carry acknowledgedAt (ISO timestamp, or null for a resolved/merged incident that was never acknowledged). The incident counts as acknowledged when acknowledgedAt is set or status is resolved or merged; do not infer it from acknowledgedBy, which is null when an API token acknowledged.

200 OK, incident was already acknowledged:

{
  "acknowledged": true,
  "alreadyAcknowledged": true,
  "status": "investigating",
  "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo",
  "acknowledgedAt": "2026-07-17T09:20:00.000Z"
}

Common errorsCopy Anchor Link

• 401 Unauthorized when not authenticated
• 403 Forbidden (customerScopedTokenForbidden) when using a customer-scoped token
• 403 Forbidden (imAccessDenied) when the session user has no IM-eligible role
• 403 Forbidden (imNotEnabled) when Incident Management is not enabled for the organization
• 400 Bad Request (invalidRequestBody) when :id is not a positive integer
• 404 Not Found (imIncidentNotFound) when the incident does not exist, or belongs to another organization

Change statusCopy Anchor Link

POST /api/im/incidents/:id/status

Moves an incident between the open statuses triggered, acknowledged, investigating, identified and monitoring. Any of the four non-triggered statuses is a valid target from any open status, not just the "next" one; triggered itself is never a target. Setting acknowledged acknowledges the incident and stops escalation as described above. Moving straight from triggered to investigating, identified or monitoring does not record an acknowledgement.

Restricted to the incident's team: you must be a member of the incident's team (teamId) or an organization admin. An organization-wide API token passes as an organization admin.

Request BodyCopy Anchor Link

Example (cURL)Copy Anchor Link

curl -X POST "$BASE_URL/api/im/incidents/42/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "investigating" }'

ResponseCopy Anchor Link

200 OK: the updated incident row (same shape as the items of List Incidents, without the enrichment fields).

{
  "id": 42,
  "organizationId": 1,
  "teamId": 3,
  "title": "Database connection pool exhausted",
  "customerId": null,
  "primarySourceId": 7,
  "severity": "sev1",
  "severityManual": false,
  "status": "investigating",
  "mergedIntoId": null,
  "escalationPolicyId": null,
  "currentTier": null,
  "escalationEpoch": 1,
  "escalationCycle": 0,
  "acknowledgedBy": "MFcTjWmYq2LpzR8vK1sXo",
  "acknowledgedAt": "2026-07-17T09:20:00.000Z",
  "snoozedUntil": null,
  "autoResolve": true,
  "resolvedBy": null,
  "resolveNote": null,
  "statuspageUpdate": null,
  "createdBy": null,
  "sourceKind": "alert",
  "isTest": false,
  "triggeredAt": "2026-07-17T09:12:00.000Z",
  "resolvedAt": null
}

Common errorsCopy Anchor Link

• 401 Unauthorized when not authenticated
• 403 Forbidden (customerScopedTokenForbidden) when using a customer-scoped token
• 403 Forbidden (imAccessDenied) when the session user has no IM-eligible role
• 403 Forbidden (imNotEnabled) when Incident Management is not enabled for the organization
• 403 Forbidden (imTeamMembershipRequired) when you are neither a member of the incident's team nor an organization admin
• 400 Bad Request (invalidRequestBody) when :id is not a positive integer, or status is missing or not a known status value
• 404 Not Found (imIncidentNotFound) when the incident does not exist, or belongs to another organization
• 422 Unprocessable Entity (imIncidentInvalidStatusTransition) when status is triggered, resolved or merged, the incident is already resolved/merged, or status equals its current status
• 409 Conflict (imIncidentStatusConflict) when the incident's status changed concurrently between the read and the write, safe to retry