Incidents API

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.

Prefer to work in the dashboard? See Create an Incident and Acknowledge and hand off for the UI walkthroughs.

If you also want each transition to publish a customer-visible message on your public status page, use POST /v1/incidents/{id}/updates with visibility: 'public' instead — one call posts the message and advances the status. See Incident Updates for the data model.

Prerequisites

A scaling.cloud API key. You can find or create one in Settings → API Access in the dashboard. See Authentication for key format and security practices.
curl or any HTTP client.

Create an incident

Send a POST request to /api/incidents with a title, severity, and optional description.

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"
  }'

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.

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

{
  "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"
  }
}

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

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 guide for setting up schedules and policies.

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:

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:

{
  "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.

Continue through the lifecycle

Once a fix is deployed, transition to monitoring to indicate you are watching for confirmation that the fix holds.

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:

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:

{
  "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"
  }
}

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

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:

curl https://api.scaling.cloud/v1/incidents/inc_01jqm5x3k8vz9e2f4g7h \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "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."
      }
    ]
  }
}

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; for the dashboard and Slack flows, see the UI guide. Acknowledge stops further escalation and records that you are on the page. It does not change the incident’s status.

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.

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.

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.

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

Get Started

API Guides

Infrastructure as Code

AWS CloudWatch

Inbound Webhooks

MCP Server

Prerequisites

Acknowledge and hand off a page

​Prerequisites

​Acknowledge and hand off a page

Prerequisites

Acknowledge and hand off a page