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.

An escalation policy defines the chain of responders that Scaling notifies when an incident is opened. Each layer targets an on-call schedule (or a specific set of users) and has an acknowledgment timeout. If no one on that layer acknowledges the incident within the timeout window, Scaling moves to the next layer.

​
Prerequisites

  • At least one on-call schedule created. See Set Up On-call if you haven’t created one yet.
  • A Scaling API key.
1

Create an escalation policy

Send a POST request to /api/escalation/policies with a name and optional description.
curl -X POST https://api.scaling.cloud/v1/escalation/policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Platform Default",
    "description": "Default escalation for platform incidents"
  }'
The response returns the new policy:
{
  "data": {
    "id": "pol_01jqm5x3k8vz9e2f4g7h",
    "orgId": "org_01jqm4ab2c3de5fg6hij",
    "name": "Platform Default",
    "description": "Default escalation for platform incidents",
    "createdBy": "user_01jqm3xy4z5abc6de7fg",
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:00:00.000Z"
  }
}
The policy has no layers yet—add them in the next step.
2

Add escalation layers

Each layer specifies a position, an ackTimeoutMinutes, and a target. The target is either an on-call schedule or a direct list of users.Add layer 1 — targets your primary on-call schedule with a 5-minute acknowledgment timeout:
curl -X POST https://api.scaling.cloud/v1/escalation/policies/pol_01jqm5x3k8vz9e2f4g7h/layers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 1,
    "ackTimeoutMinutes": 5,
    "target": {
      "type": "schedule",
      "scheduleId": "sched_01jqm5x3k8vz9e2f4g7h"
    }
  }'
Response:
{
  "data": {
    "id": "layer_01jqm6a2b3cd4ef5gh6i",
    "policyId": "pol_01jqm5x3k8vz9e2f4g7h",
    "orgId": "org_01jqm4ab2c3de5fg6hij",
    "position": 1,
    "ackTimeoutMinutes": 5,
    "target": {
      "type": "schedule",
      "scheduleId": "sched_01jqm5x3k8vz9e2f4g7h"
    },
    "createdAt": "2026-04-07T10:05:00.000Z",
    "updatedAt": "2026-04-07T10:05:00.000Z"
  }
}
Add layer 2 — targets a secondary schedule with a 10-minute timeout. This layer fires if no one on the first schedule acknowledges within 5 minutes:
curl -X POST https://api.scaling.cloud/v1/escalation/policies/pol_01jqm5x3k8vz9e2f4g7h/layers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 2,
    "ackTimeoutMinutes": 10,
    "target": {
      "type": "schedule",
      "scheduleId": "sched_01jqm7c3d4ef5gh6ij7k"
    }
  }'
Response:
{
  "data": {
    "id": "layer_01jqm7b3c4de5fg6hi7j",
    "policyId": "pol_01jqm5x3k8vz9e2f4g7h",
    "orgId": "org_01jqm4ab2c3de5fg6hij",
    "position": 2,
    "ackTimeoutMinutes": 10,
    "target": {
      "type": "schedule",
      "scheduleId": "sched_01jqm7c3d4ef5gh6ij7k"
    },
    "createdAt": "2026-04-07T10:06:00.000Z",
    "updatedAt": "2026-04-07T10:06:00.000Z"
  }
}
If no one acknowledges an incident within a layer’s ackTimeoutMinutes, Scaling automatically notifies the next layer in the policy. If all layers are exhausted without an acknowledgment, Scaling stops escalating but the incident remains open. Make sure your final layer has a long enough timeout or targets a reliable fallback—such as a manager or secondary team.
You can also target specific users directly instead of a schedule by using "type": "users" with a userIds array:
{
  "position": 3,
  "ackTimeoutMinutes": 15,
  "target": {
    "type": "users",
    "userIds": ["user_01jqm3xy4z5abc6de7fg"]
  }
}
3

Attach the policy to an incident

Pass the policy ID in the escalationPolicyId field when creating an incident. Scaling immediately begins notifying the first layer’s on-call responders.
curl -X POST https://api.scaling.cloud/v1/incidents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Payment service degraded",
    "severity": "critical",
    "description": "Checkout success rate dropped to 60% in the last 10 minutes",
    "escalationPolicyId": "pol_01jqm5x3k8vz9e2f4g7h"
  }'
The response confirms the policy is attached:
{
  "data": {
    "id": "inc_01jqm9d5e6fg7hi8jk9l",
    "orgId": "org_01jqm4ab2c3de5fg6hij",
    "title": "Payment service degraded",
    "description": "Checkout success rate dropped to 60% in the last 10 minutes",
    "severity": "critical",
    "status": "investigating",
    "ownerId": null,
    "escalationPolicyId": "pol_01jqm5x3k8vz9e2f4g7h",
    "createdBy": "user_01jqm3xy4z5abc6de7fg",
    "createdAt": "2026-04-07T10:10:00.000Z",
    "updatedAt": "2026-04-07T10:10:00.000Z"
  }
}
4

Reorder layers

If you need to change the escalation order, send a PUT request to /api/escalation/policies/{policyId}/layers/order with the full ordered list of layer IDs. The array order determines the new position values.
curl -X PUT https://api.scaling.cloud/v1/escalation/policies/pol_01jqm5x3k8vz9e2f4g7h/layers/order \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "layerIds": [
      "layer_01jqm7b3c4de5fg6hi7j",
      "layer_01jqm6a2b3cd4ef5gh6i"
    ]
  }'
The response returns all layers with updated positions:
{
  "data": [
    {
      "id": "layer_01jqm7b3c4de5fg6hi7j",
      "policyId": "pol_01jqm5x3k8vz9e2f4g7h",
      "orgId": "org_01jqm4ab2c3de5fg6hij",
      "position": 1,
      "ackTimeoutMinutes": 10,
      "target": {
        "type": "schedule",
        "scheduleId": "sched_01jqm7c3d4ef5gh6ij7k"
      },
      "createdAt": "2026-04-07T10:06:00.000Z",
      "updatedAt": "2026-04-07T10:20:00.000Z"
    },
    {
      "id": "layer_01jqm6a2b3cd4ef5gh6i",
      "policyId": "pol_01jqm5x3k8vz9e2f4g7h",
      "orgId": "org_01jqm4ab2c3de5fg6hij",
      "position": 2,
      "ackTimeoutMinutes": 5,
      "target": {
        "type": "schedule",
        "scheduleId": "sched_01jqm5x3k8vz9e2f4g7h"
      },
      "createdAt": "2026-04-07T10:05:00.000Z",
      "updatedAt": "2026-04-07T10:20:00.000Z"
    }
  ]
}
You must include every layer ID in the request—the API will reject a layerIds array that doesn’t match the full set of layers on the policy.