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 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 looks at the schedule’s active layers to determine who to notify.

​
Schedule fields

FieldRequiredNotes
nameYes1–255 characters. Must be unique within your organization.
descriptionNoOptional context about the schedule’s purpose.
timezoneYesAn 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 Incident.ownerId 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 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

FieldRequiredNotes
nameYes1–255 characters. Must be unique within the schedule.
positionAutoAssigned by the server. Lower = higher precedence; position 0 is the owner-bearing layer. Change with the layer reorder endpoint.
rotationTypeYesdaily, weekly, or custom. See rotation types below.
rotationLengthDaysYesThe length of each rotation shift in days. Minimum 1.
handoffTimeYesThe time of day when the rotation shifts to the next participant. Format: HH:MM (24-hour), interpreted in the schedule’s timezone.
effectiveFromYesISO 8601 datetime. When this layer becomes active.
effectiveUntilNoISO 8601 datetime. When this layer expires. Omit for an open-ended layer.
participantIdsYesAn ordered list of org member IDs who rotate through this layer. 1–100 members. The order determines rotation sequence.

​
Rotation types

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"
}
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 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 Incident.ownerId). 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.