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

# Incidents API

> Create and manage incidents programmatically with the scaling.cloud API — open an incident, transition it through its lifecycle, resolve it with a note, and acknowledge or hand off a page.

This guide drives the full incident lifecycle over the REST API: open an incident, transition it through its statuses, resolve it with a note, and acknowledge or hand off a page. The flow shown here uses the simple `PATCH /status` endpoint with an optional staff-only `resolutionNote`.

<Tip>
  Prefer to work in the dashboard? See [Create an Incident](/guides/create-first-incident) and [Acknowledge and hand off](/guides/acknowledge-and-handoff) for the UI walkthroughs.
</Tip>

<Tip>
  If you also want each transition to publish a customer-visible message on your
  public status page, use [`POST /v1/incidents/{id}/updates`](/api/incidents/updates-put) with `visibility: 'public'` instead —
  one call posts the message and advances the status. See [Incident
  Updates](/concepts/incidents#incident-updates) for the data model.
</Tip>

## Prerequisites

* A scaling.cloud API key. You can find or create one in **Settings → API Access** in the dashboard. See [Authentication](/authentication) for key format and security practices.
* `curl` or any HTTP client.

<Steps>
  <Step title="Create an incident">
    Send a `POST` request to `/api/incidents` with a title, severity, and optional description.

    ```bash theme={null}
    curl -X POST https://api.scaling.cloud/v1/incidents \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Database latency spike",
        "severity": "high",
        "description": "P99 latency exceeded 2s on primary DB",
        "leadScheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }'
    ```

    <Note>
      At least one of `leadId` or `leadScheduleId` is required so the paging path always has a target — a request without either is rejected with `400`.
    </Note>

    A successful response returns the new incident object with `201 Created`:

    ```json theme={null}
    {
      "data": {
        "id": "inc_01jqm5x3k8vz9e2f4g7h",
        "orgId": "org_01jqm4ab2c3de5fg6hij",
        "title": "Database latency spike",
        "severity": "high",
        "status": "investigating",
        "affectedComponents": [],
        "createdAt": "2026-04-07T10:00:00.000Z",
        "updatedAt": "2026-04-07T10:00:00.000Z"
      }
    }
    ```

    <Note>
      Every incident starts in `investigating` status. The severity levels available are:

      | Severity   | When to use                                      |
      | ---------- | ------------------------------------------------ |
      | `critical` | Complete outage or data loss affecting all users |
      | `high`     | Major degradation affecting most users           |
      | `medium`   | Partial degradation or workaround available      |
      | `low`      | Minor issue with minimal user impact             |
    </Note>

    <Tip>
      To page the on-call responder automatically, pass `"leadScheduleId": "{scheduleId}"`. scaling.cloud will assign the current on-call responder as the incident lead and attach the matching escalation policy (if one is configured for the schedule). See the [Escalation policies API](/developers/escalation-api) guide for setting up schedules and policies.
    </Tip>
  </Step>

  <Step title="Transition the incident status">
    Move the incident forward by sending a `PATCH` request to `/api/incidents/{id}/status`. Status transitions are one-way and must follow the sequence: `investigating` → `identified` → `monitoring` → `resolved`.

    Here, you transition from `investigating` to `identified` once you've found the root cause:

    ```bash theme={null}
    curl -X PATCH https://api.scaling.cloud/v1/incidents/inc_01jqm5x3k8vz9e2f4g7h/status \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "status": "identified"
      }'
    ```

    The response reflects the updated incident:

    ```json theme={null}
    {
      "data": {
        "id": "inc_01jqm5x3k8vz9e2f4g7h",
        "orgId": "org_01jqm4ab2c3de5fg6hij",
        "title": "Database latency spike",
        "severity": "high",
        "status": "identified",
        "affectedComponents": [],
        "createdAt": "2026-04-07T10:00:00.000Z",
        "updatedAt": "2026-04-07T10:15:00.000Z"
      }
    }
    ```

    Continue transitioning through `monitoring` the same way as conditions stabilize.
  </Step>

  <Step title="Continue through the lifecycle">
    Once a fix is deployed, transition to `monitoring` to indicate you are watching for confirmation that the fix holds.

    ```bash theme={null}
    curl -X PATCH https://api.scaling.cloud/v1/incidents/inc_01jqm5x3k8vz9e2f4g7h/status \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "status": "monitoring"
      }'
    ```

    When the incident is fully mitigated and confirmed stable, transition to `resolved`. Include a `resolutionNote` to document what happened and how it was fixed:

    ```bash theme={null}
    curl -X PATCH https://api.scaling.cloud/v1/incidents/inc_01jqm5x3k8vz9e2f4g7h/status \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "status": "resolved",
        "resolutionNote": "Root cause was a missing index on the orders table. Index added and query performance returned to normal. P99 latency is back below 200ms."
      }'
    ```

    The response confirms the resolved state:

    ```json theme={null}
    {
      "data": {
        "id": "inc_01jqm5x3k8vz9e2f4g7h",
        "orgId": "org_01jqm4ab2c3de5fg6hij",
        "title": "Database latency spike",
        "severity": "high",
        "status": "resolved",
        "affectedComponents": [],
        "createdAt": "2026-04-07T10:00:00.000Z",
        "updatedAt": "2026-04-07T11:30:00.000Z"
      }
    }
    ```

    <Note>
      You must progress through each status in order: `investigating` → `identified` → `monitoring` → `resolved`. You cannot skip steps or go backwards. Resolution notes can be included on any transition and are up to 2,000 characters.

      **`resolved` is terminal.** Once an incident is resolved, no further status changes or updates can be posted on it (you may still [redact](/api/incidents/updates-redact) earlier updates). If you need a post-incident write-up to appear on the status page, publish it as a `public` update **before** transitioning to `resolved`.
    </Note>
  </Step>

  <Step title="Retrieve the full incident history">
    Fetch the incident by ID to see the complete status history, including who made each change, when, and any resolution notes attached:

    ```bash theme={null}
    curl https://api.scaling.cloud/v1/incidents/inc_01jqm5x3k8vz9e2f4g7h \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "data": {
        "id": "inc_01jqm5x3k8vz9e2f4g7h",
        "orgId": "org_01jqm4ab2c3de5fg6hij",
        "title": "Database latency spike",
        "severity": "high",
        "status": "resolved",
        "affectedComponents": [],
        "createdAt": "2026-04-07T10:00:00.000Z",
        "updatedAt": "2026-04-07T11:30:00.000Z",
        "statusHistory": [
          {
            "id": "sh_01jqm5y1a2bc3de4fg5h",
            "status": "investigating",
            "changedAt": "2026-04-07T10:00:00.000Z",
            "resolutionNote": null
          },
          {
            "id": "sh_01jqm6a2b3cd4ef5gh6i",
            "status": "identified",
            "changedAt": "2026-04-07T10:15:00.000Z",
            "resolutionNote": null
          },
          {
            "id": "sh_01jqm7b3c4de5fg6hi7j",
            "status": "monitoring",
            "changedAt": "2026-04-07T10:45:00.000Z",
            "resolutionNote": null
          },
          {
            "id": "sh_01jqm8c4d5ef6gh7ij8k",
            "status": "resolved",
            "changedAt": "2026-04-07T11:30:00.000Z",
            "resolutionNote": "Root cause was a missing index on the orders table. Index added and query performance returned to normal. P99 latency is back below 200ms."
          }
        ]
      }
    }
    ```
  </Step>
</Steps>

## Acknowledge and hand off a page

When an incident pages a responder, two endpoints cover the everyday actions: acknowledging the page to stop escalation, and handing it off to someone else. For the concepts, see [Acknowledgment and handoff](/concepts/acknowledgment-and-handoff); for the dashboard and Slack flows, see the [UI guide](/guides/acknowledge-and-handoff).

**Acknowledge** stops further escalation and records that you are on the page. It does not change the incident's status.

```bash theme={null}
curl -X POST https://api.scaling.cloud/v1/incidents/{incidentId}/acknowledge \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Returns the updated incident with the new escalation state. Calling acknowledge on an already-acknowledged or resolved incident is a no-op.

**Hand off** transfers the lead role to another responder and restarts the escalation timer on the current layer.

```bash theme={null}
curl -X POST https://api.scaling.cloud/v1/incidents/{incidentId}/handoff \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetUserId": "user_2xyz..."}'
```

The `targetUserId` must be a member of the same organization. Handing off to a non-member returns `400 invalid_target_user`.

<Warning>
  A handoff restarts the escalation timer for the new lead. If they don't acknowledge within the layer's `ackTimeoutMinutes`, escalation resumes from where it left off.
</Warning>

Both actions are appended to the incident's paging audit trail (`incident_acknowledged`, `incident_handed_off`), which is returned alongside the incident record from `GET /v1/incidents/{id}`.