On-call Schedules

An on-call schedule defines a group of team members who rotate responsibility for responding to incidents. Each schedule has one or more rotation layers that determine who is on-call at any given time based on a repeating cycle. Schedules are the building blocks for escalation policies. When an escalation policy targets a schedule, scaling.cloud looks at the schedule’s active layers to determine who to notify.

Schedule fields

Field	Required	Notes
`name`	Yes	1–255 characters. Must be unique within your organization.
`description`	No	Optional context about the schedule’s purpose.
`timezone`	Yes	An IANA timezone identifier, e.g. `America/New_York` or `Europe/London`. All handoff times are interpreted in this timezone.

Always set the schedule timezone to match where the majority of your on-call team is based. This ensures handoff times behave as expected — for example, a 09:00 handoff will fire at 9 AM local time for your team.

Rotation layers

Each schedule can have multiple rotation layers. A layer defines a repeating on-call cycle for a specific group of participants. Layers within a schedule are ordered by position — an integer (unique per schedule) where position 0 is the owner-bearing layer. Lower position = higher precedence for ownership resolution. The position determines:

Which layer’s resolved participant becomes the Schedule Owner (used to populate the incident Lead at incident creation).
Which layer the schedule-wide override displaces when the override is active.
The display order of layers in the UI.

New layers are appended at the next available position. Use the schedule edit screen — or the layer reorder endpoint — to change the order. When scaling.cloud pages for an incident whose escalation policy targets this schedule, every currently-active layer’s resolved participant gets paged — not just position 0. Use position to decide who owns the schedule, not who gets paged.

Layer fields

Field	Required	Notes
`name`	Yes	1–255 characters. Must be unique within the schedule.
`position`	Auto	Assigned by the server. Lower = higher precedence; position 0 is the owner-bearing layer. Change with the layer reorder endpoint.
`rotationType`	Yes	`daily`, `weekly`, or `custom`. See rotation types below.
`rotationLengthDays`	Yes	The length of each rotation shift in days. Minimum 1.
`handoffTime`	Yes	The time of day when the rotation shifts to the next participant. Format: `HH:MM` (24-hour), interpreted in the schedule’s timezone.
`effectiveFrom`	Yes	ISO 8601 datetime. When this layer becomes active.
`effectiveUntil`	No	ISO 8601 datetime. When this layer expires. Omit for an open-ended layer.
`participantIds`	Yes	An ordered list of org member IDs who rotate through this layer. 1–100 members. The order determines rotation sequence.

Rotation types

Daily
Weekly
Custom

Each participant is on-call for one calendar day before the rotation shifts to the next person. Set rotationLengthDays to 1.

{
  "rotationType": "daily",
  "rotationLengthDays": 1,
  "handoffTime": "09:00"
}

Each participant is on-call for one full week. Set rotationLengthDays to 7.

{
  "rotationType": "weekly",
  "rotationLengthDays": 7,
  "handoffTime": "09:00"
}

Each participant is on-call for a custom number of days. Set rotationLengthDays to any value of 1 or more.

{
  "rotationType": "custom",
  "rotationLengthDays": 3,
  "handoffTime": "08:00"
}

The rotationType field is informational and used to label the rotation in the UI. The actual rotation calculation always uses rotationLengthDays.

Participant order

The order of participantIds defines the rotation sequence. The first participant in the list is on-call starting from effectiveFrom. After rotationLengthDays days at handoffTime, the second participant takes over — and so on, cycling back to the first when the list is exhausted. To change the rotation order, update the layer with the full participantIds array in the new sequence.

Querying who is on-call

You can ask scaling.cloud who is currently on-call for any schedule. The GET /oncall/schedules/{scheduleId}/resolve endpoint returns three views in one response:

owner — the single Schedule Owner (used to populate the incident Lead). The lowest-positioned currently-active layer’s resolved participant, with that layer’s override applied if active. Falls through to the next position when position 0 is between effective windows. null if no layer is active.
pagingTargets — the full set of users an escalation policy targeting this schedule would page right now. One entry per currently-active layer in position order, with each layer’s override applied.
currentOncallView — a richer breakdown with per-entry position, source (rotation or override), and (when applicable) the displaced overriddenUser and viaOverrideId.

Pass an at query parameter to resolve at a specific point in time instead of now.

{
  "owner": {
    "user": {
      "id": "user_bbb",
      "firstName": "Alice",
      "lastName": "Chen",
      "email": "alice@acme.io"
    }
  },
  "pagingTargets": [
    {
      "user": {
        "id": "user_bbb",
        "firstName": "Alice",
        "lastName": "Chen",
        "email": "alice@acme.io"
      }
    }
  ],
  "currentOncallView": {
    "scheduleId": "sch_01j...",
    "resolvedAt": "2026-04-07T10:00:00.000Z",
    "owner": {
      "user": {
        "id": "user_bbb",
        "firstName": "Alice",
        "lastName": "Chen",
        "email": "alice@acme.io"
      }
    },
    "entries": [
      {
        "rotationLayerId": "lay_01j...",
        "rotationLayerName": "Primary",
        "position": 0,
        "user": {
          "id": "user_bbb",
          "firstName": "Alice",
          "lastName": "Chen",
          "email": "alice@acme.io"
        },
        "source": "rotation"
      }
    ]
  }
}

If entries is empty (and therefore owner is null and pagingTargets is []), no layers are active for that schedule at the requested time.

Get Started

Core Concepts

Integrations

Guides

Schedule fields

Rotation layers

Layer fields

Rotation types

Participant order

Querying who is on-call

​Schedule fields

​Rotation layers

​Layer fields

​Rotation types

​Participant order

​Querying who is on-call

Schedule fields

Rotation layers

Layer fields

Rotation types

Participant order

Querying who is on-call