Skip to main content
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.cloud 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

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

​
Layer fields

Each layer in a policy has the following fields:

​
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.cloud resolves the active on-call participant at the time the layer fires.
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.

​
Working hours conditions

A layer can carry an optional working hours condition that gates whether it participates based on the time of day — the foundation for follow-the-sun routing. The condition references a working hours set and a direction: { workingHoursId, when }, where when is during (participate only inside the set’s windows) or outside (participate only outside them). A layer with no condition always participates. Three rules govern how conditions behave:
  • Skip, never wait. When escalation reaches a layer whose condition does not hold, scaling.cloud skips it and moves to the next layer immediately. There is no way to hold a page until working hours begin.
  • Evaluated at fire time. A condition is checked at the instant escalation reaches the layer, never snapshotted at incident creation. A page raised at 08:50 that escalates at 09:05 correctly reaches a layer gated during 09:00–17:00.
  • Backstop. If every layer’s condition fails at an evaluation instant, the last layer is paged unconditionally — a page never silently dies to misconfiguration.
When you save a policy whose layers are all conditional, scaling.cloud shows a non-blocking advisory so the backstop behavior is legible, and the policy detail page offers a “who would be paged right now” resolution preview. See Working hours for the full model and the Follow-the-sun escalation guide for a walkthrough.

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