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

# Escalation Policies

> Define an ordered chain of responders so that if one layer doesn't acknowledge an incident in time, the next is automatically notified.

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

| Position | Target                      | Timeout    |
| -------- | --------------------------- | ---------- |
| 1        | Platform On-call (schedule) | 5 minutes  |
| 2        | Senior Engineers (schedule) | 15 minutes |
| 3        | Engineering 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

| Field         | Required | Notes                                             |
| ------------- | -------- | ------------------------------------------------- |
| `name`        | Yes      | 1–255 characters. Must be unique within your org. |
| `description` | No       | Optional context about when to use this policy.   |

## Layer fields

Each layer in a policy has the following fields:

| Field               | Required | Notes                                                                                          |
| ------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `position`          | Yes      | Positive integer. Determines evaluation order. Lower position = notified first.                |
| `ackTimeoutMinutes` | Yes      | How long to wait (in minutes) before escalating to the next layer. Min 1, max 10,080 (7 days). |
| `target`            | Yes      | Who 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.

<Tabs>
  <Tab title="Schedule target">
    Notifies whoever is currently on-call in the referenced schedule. scaling.cloud resolves the active on-call participant at the time the layer fires.

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Users target">
    Notifies a fixed list of 1–100 specific team members, regardless of any schedule.

    ```json theme={null}
    {
      "position": 2,
      "ackTimeoutMinutes": 15,
      "target": {
        "type": "users",
        "userIds": ["user_aaa", "user_bbb"]
      }
    }
    ```

    Use this for a named backup — for example, a manager or senior engineer you always want as a final escalation point.
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

## 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](/concepts/working-hours) 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](/concepts/working-hours) for the full model and the [Follow-the-sun escalation](/guides/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.

```json theme={null}
{
  "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.

<Note>
  You cannot delete a policy while it is attached to an active (open) incident. Resolve or reassign those incidents first.
</Note>

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

<Tip>
  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.
</Tip>