Skip to main content

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.

This guide walks you through creating an incident via the Scaling API, transitioning it through its lifecycle, and resolving it with a note. The flow shown here uses the simple PATCH /status endpoint with an optional staff-only resolutionNote.
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 API key. You can find or create one in Settings → API Access in the dashboard.
  • curl or any HTTP client.
1

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",
    "ownerScheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'
At least one of ownerId or ownerScheduleId 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:
SeverityWhen to use
criticalComplete outage or data loss affecting all users
highMajor degradation affecting most users
mediumPartial degradation or workaround available
lowMinor issue with minimal user impact
To page the on-call responder automatically, pass "ownerScheduleId": "{scheduleId}". Scaling will assign the current on-call responder as the incident owner and attach the matching escalation policy (if one is configured for the schedule). See the Configure Escalation guide for setting up schedules and policies.
2

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

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

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