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 who to notify when an incident occurs, and what happens if no one responds. Policies are made up of an ordered sequence of layers. Each layer targets a specific on-call schedule or a fixed list of team members. If no one acknowledges within the layer’s timeout, Scaling moves to the next layer. Attaching a policy to an incident ensures that alerts don’t go unanswered — even if the first responder is unavailable.

​
How escalation works

When an incident with an escalation policy is triggered:
  1. Layer 1 is notified — for example, the Platform On-call schedule.
  2. If no one acknowledges within the layer’s ackTimeoutMinutes, Layer 2 is notified — for example, a Senior Engineers schedule.
  3. This continues down the chain until someone acknowledges or all layers have been notified.
Layers are evaluated in order by their position. Lower position numbers are notified first.

​
Example policy

PositionTargetTimeout
1Platform On-call (schedule)5 minutes
2Senior Engineers (schedule)15 minutes
3Engineering Manager (user)30 minutes
In this example, Layer 1 notifies whoever is currently on-call in the Platform On-call schedule. If no one responds in 5 minutes, Layer 2 notifies the Senior Engineers schedule. If that layer also goes unacknowledged for 15 minutes, the Engineering Manager is paged directly.

​
Policy fields

FieldRequiredNotes
nameYes1–255 characters. Must be unique within your org.
descriptionNoOptional context about when to use this policy.

​
Layer fields

Each layer in a policy has the following fields:
FieldRequiredNotes
positionYesPositive integer. Determines evaluation order. Lower position = notified first.
ackTimeoutMinutesYesHow long to wait (in minutes) before escalating to the next layer. Min 1, max 10,080 (7 days).
targetYesWho to notify. Either an on-call schedule or a list of specific users.

​
Layer targets

Each layer has exactly one target — either a schedule or a direct list of users.
Notifies whoever is currently on-call in the referenced schedule. Scaling resolves the active on-call participant at the time the layer fires.
{
  "position": 1,
  "ackTimeoutMinutes": 5,
  "target": {
    "type": "schedule",
    "scheduleId": "sch-uuid-..."
  }
}
Use this when you want the layer to always reach the right person based on your rotation — without updating the policy every time the on-call person changes.
If a schedule referenced by a layer is deleted, that layer’s target becomes empty. The layer remains in the policy but will not notify anyone. Review your policies after deleting a schedule.

​
Attaching a policy to an incident

You can attach a policy to an incident when you create it by passing escalationPolicyId. The policy must belong to the same organization. 
{
  "title": "API gateway returning 500s",
  "severity": "critical",
  "escalationPolicyId": "a1b2c3d4-e5f6-..."
}
If you don’t attach a policy at creation time, you can assign one later by updating the incident.
You cannot delete a policy while it is attached to an active (open) incident. Resolve or reassign those incidents first.

​
Reordering layers

You can change the order of layers at any time by submitting a full ordered list of layer IDs. Scaling reassigns positions so the first ID in your list becomes position 1, the second becomes position 2, and so on.
Start with a tight timeout on Layer 1 (e.g., 5 minutes) for critical policies. Longer timeouts on later layers give escalated responders time to assess the situation before it moves further up the chain.