> ## 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.

# Update Status

> Transitions an incident to the next status in its lifecycle.

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.

<Tip>
  This endpoint coexists with [Post Incident Update](./updates-put). 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.
</Tip>

## Status lifecycle

```
investigating → identified → monitoring → resolved
```

| Current status  | Valid next status  |
| --------------- | ------------------ |
| `investigating` | `identified`       |
| `identified`    | `monitoring`       |
| `monitoring`    | `resolved`         |
| `resolved`      | — (terminal state) |

<Warning>
  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`.
</Warning>

## Path parameters

<ParamField path="id" type="string" required>
  The UUID of the incident to update.
</ParamField>

## Request body

<ParamField body="status" type="string" required>
  The status to transition to. Must be the next valid status in the lifecycle sequence. One of `investigating`, `identified`, `monitoring`, or `resolved`.
</ParamField>

<ParamField body="resolutionNote" type="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.
</ParamField>

## Response

Returns the updated incident object.

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string" required>
      Unique identifier for the incident (UUID).
    </ResponseField>

    <ResponseField name="orgId" type="string" required>
      The organization this incident belongs to.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Short title describing the incident.
    </ResponseField>

    <ResponseField name="severity" type="string" required>
      Severity level: `critical`, `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      The new current status after the transition.
    </ResponseField>

    <ResponseField name="affectedComponents" type="array of object" required>
      Components affected by this incident. Each entry has `id` and `name`. Empty array if none.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of when the incident was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of when the incident was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Code                        | Description                                                                     |
| ------ | --------------------------- | ------------------------------------------------------------------------------- |
| `400`  | `invalid_status_transition` | The requested status does not follow the required sequence.                     |
| `400`  | `incident_resolved`         | The incident is already `resolved`; no further status changes are accepted.     |
| `401`  | `not_authorized`            | Missing or invalid API key.                                                     |
| `404`  | `not_found`                 | No incident with the given ID exists in your organization.                      |
| `422`  | —                           | Request body failed validation (e.g. `resolutionNote` exceeds 2000 characters). |
| `500`  | `server_error`              | An unexpected error occurred on our side.                                       |

<RequestExample>
  ```bash Transition to identified theme={null}
  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"
    }'
  ```

  ```bash Resolve with a note theme={null}
  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": "resolved",
      "resolutionNote": "Root cause was a misconfigured rate limit on the payment gateway introduced in deploy v3.14.2. Rolled back and applied fix in v3.14.3. Monitoring confirms error rate has returned to baseline."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "type": "invalid_request_error",
    "code": "invalid_status_transition",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 401 theme={null}
  {
    "statusCode": 401,
    "type": "not_authorized_error",
    "code": "not_authorized",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "type": "invalid_request_error",
    "code": "not_found",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 500 theme={null}
  {
    "statusCode": 500,
    "type": "invalid_error",
    "code": "server_error",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```
</ResponseExample>