Prerequisites
- At least one on-call schedule created. See the On-call schedules API if you haven’t created one yet.
- A scaling.cloud API key.
1
Create an escalation policy
Send a The response returns the new policy:The policy has no layers yet—add them in the next step.
POST request to /api/escalation/policies with a name and optional description.2
Add escalation layers
Each layer specifies a Response: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:Response:You can also target specific users directly instead of a schedule by using
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:If no one acknowledges an incident within a layer’s
ackTimeoutMinutes, scaling.cloud automatically notifies the next layer in the policy. If all layers are exhausted without an acknowledgment, scaling.cloud 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."type": "users" with a userIds array:3
Attach the policy to an incident
Pass the policy ID in the The response confirms the policy is attached:
escalationPolicyId field when creating an incident. scaling.cloud immediately begins notifying the first layer’s on-call responders.4
Reorder layers
If you need to change the escalation order, send a The response returns all layers with updated positions:You must include every layer ID in the request—the API will reject 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.layerIds array that doesn’t match the full set of layers on the policy.Follow-the-sun: gate layers with working hours
Follow-the-sun escalation pages the team that is awake. You gate a policy’s layers with working hours conditions so a daytime incident reaches your UK rotation during UK hours and your US rotation otherwise — without maintaining parallel policies. For the concepts, see Working hours; for the dashboard walkthrough, see Follow-the-sun escalation.1
Create the working hours sets
Create one set per region. Each set carries its own timezone — it is never inferred from a schedule — and one or more weekly windows.Create UK office hours:Create US office hours:
days are ISO weekday numbers — 1 = Monday through 7 = Sunday — and start/end are 24-hour HH:MM times in the set’s timezone. Note each id in the response; you’ll reference it from a layer condition next.2
Gate the layers with conditions
Order two conditional layers on your escalation policy: page the UK rotation Add layer 2 — the US rotation, gated Use
during UK hours, then the US rotation during US hours. A layer’s condition has the shape { workingHoursId, when }, where when is during or outside.Add layer 1 — the UK rotation, gated during UK office hours:during US office hours:outside when you want a layer to participate only outside a set’s windows — for example a night-shift layer gated outside UK office hours. Omit condition to make a layer unconditional.Two rules make this safe. Skip, never wait: a layer whose condition does not hold is skipped and escalation proceeds to the next layer immediately. Backstop: if every layer’s condition fails at an evaluation instant, the last layer is paged unconditionally, so a page never silently dies to misconfiguration. Conditions are evaluated at the instant escalation reaches the layer, never at incident creation. A good pattern is to make your final layer unconditional.
Next steps
Manage working hours as code
The
scaling_working_hours Terraform resource and the step condition block.