Skip to main content
PATCH
/
v1
/
incidents
/
{id}
/
status
curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "identified"
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_01HX4K9MNPQRST",
    "title": "Payment service elevated error rate",
    "severity": "critical",
    "status": "identified",
    "affectedComponents": [
      { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
    ],
    "createdAt": "2025-04-07T08:23:11.000Z",
    "updatedAt": "2025-04-07T09:15:44.000Z"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Advances an incident through its fixed lifecycle. Each call moves the incident exactly one step forward. You cannot skip steps, go backwards, or re-open a resolved incident.
This endpoint coexists with Post Incident Update. They are not redundant:
  • Use PATCH /status for a simple, status-only transition with an optional staff-only resolutionNote. The note never reaches your public status page.
  • Use POST /updates when you want the same write to publish a customer-visible message on your status page (visibility: 'public', statusChange: <next>, body: <what customers should read>), or when you want to post a free-text note without changing status.
Internally, PATCH /status is now a thin alias that posts an internal update via the same engine path.

​
Status lifecycle

investigating → identified → monitoring → resolved
Current statusValid next status
investigatingidentified
identifiedmonitoring
monitoringresolved
resolved— (terminal state)
Status transitions are one-way and must follow the exact sequence above. Attempting to transition to any status other than the immediate next step — including skipping ahead, going backwards, or updating a resolved incident — will return a 400 error with code invalid_status_transition.

​
Path parameters

​
id
string
required
The UUID of the incident to update.

​
Request body

​
status
string
required
The status to transition to. Must be the next valid status in the lifecycle sequence. One of investigating, identified, monitoring, or resolved.
​
resolutionNote
string
Optional note to record alongside this transition. Must be between 1 and 2000 characters. Leading and trailing whitespace is trimmed automatically. Commonly used when transitioning to resolved to summarize the root cause and fix.

​
Response

Returns the updated incident object.
​
data
object
required

​
Error responses

StatusCodeDescription
400invalid_status_transitionThe requested status does not follow the required sequence.
400incident_resolvedThe incident is already resolved; no further status changes are accepted.
401not_authorizedMissing or invalid API key.
404not_foundNo incident with the given ID exists in your organization.
422—Request body failed validation (e.g. resolutionNote exceeds 2000 characters).
500server_errorAn unexpected error occurred on our side.
curl --request PATCH \
  --url "https://api.scaling.cloud/v1/incidents/YOUR_INCIDENT_ID/status" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "identified"
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_01HX4K9MNPQRST",
    "title": "Payment service elevated error rate",
    "severity": "critical",
    "status": "identified",
    "affectedComponents": [
      { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
    ],
    "createdAt": "2025-04-07T08:23:11.000Z",
    "updatedAt": "2025-04-07T09:15:44.000Z"
  }
}