On-call schedules API

On-call schedules define who is responsible for responding to incidents during any given time window. A schedule contains one or more rotation layers, each with its own rotation type, handoff time, and list of participants. This guide walks you through creating a schedule, adding a rotation layer, and checking who is currently on call over the REST API.

Prefer to work in the dashboard? See Set Up On-call for the UI walkthrough.

Create a schedule

Send a POST request to /api/oncall/schedules with a name and IANA timezone identifier.

curl -X POST https://api.scaling.cloud/v1/oncall/schedules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Platform On-call",
    "description": "Primary platform rotation",
    "timezone": "America/New_York"
  }'

A successful response returns the new schedule:

{
  "data": {
    "id": "sched_01jqm5x3k8vz9e2f4g7h",
    "orgId": "org_01jqm4ab2c3de5fg6hij",
    "name": "Platform On-call",
    "description": "Primary platform rotation",
    "timezone": "America/New_York",
    "createdBy": "user_01jqm3xy4z5abc6de7fg",
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:00:00.000Z"
  }
}

Always use IANA timezone identifiers (e.g., America/New_York, Europe/London, Asia/Tokyo) rather than abbreviations like EST or UTC+5. IANA identifiers automatically account for daylight saving time changes. You can find the full list at iana.org/time-zones or use a reference like the tz database.

Add a rotation layer

A rotation layer defines when the schedule is active and which participants rotate through it. Send a POST request to /api/oncall/schedules/{scheduleId}/layers, replacing {scheduleId} with the ID returned in the previous step.

curl -X POST https://api.scaling.cloud/v1/oncall/schedules/sched_01jqm5x3k8vz9e2f4g7h/layers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary",
    "rotationType": "weekly",
    "rotationLengthDays": 7,
    "handoffTime": "09:00",
    "effectiveFrom": "2026-01-01T00:00:00.000Z",
    "participantIds": ["user_aaa", "user_bbb", "user_ccc"]
  }'

The response returns the created layer:

{
  "data": {
    "id": "layer_01jqm6a2b3cd4ef5gh6i",
    "scheduleId": "sched_01jqm5x3k8vz9e2f4g7h",
    "orgId": "org_01jqm4ab2c3de5fg6hij",
    "name": "Primary",
    "rotationType": "weekly",
    "rotationLengthDays": 7,
    "handoffTime": "09:00",
    "effectiveFrom": "2026-01-01T00:00:00.000Z",
    "effectiveUntil": null,
    "participantIds": ["user_aaa", "user_bbb", "user_ccc"],
    "createdAt": "2026-04-07T10:05:00.000Z",
    "updatedAt": "2026-04-07T10:05:00.000Z"
  }
}

Key fields to know:

Field	Description
`rotationType`	One of `daily`, `weekly`, or `custom`
`rotationLengthDays`	Number of days per rotation shift (minimum 1)
`handoffTime`	Time of day the rotation switches, in `HH:MM` 24-hour format
`effectiveFrom`	ISO 8601 datetime when this layer becomes active
`effectiveUntil`	Optional ISO 8601 datetime when this layer expires; `null` means it runs indefinitely
`participantIds`	Ordered list of user IDs who rotate through the layer

Participants rotate in the order listed. The first user in participantIds is on call starting at effectiveFrom, then each subsequent user takes over after rotationLengthDays days at handoffTime.

Check who is currently on call

Query the schedule to see which participant is currently on call. Send a GET request to /api/oncall/schedules/{scheduleId}/resolve.

curl https://api.scaling.cloud/v1/oncall/schedules/sched_01jqm5x3k8vz9e2f4g7h/resolve \
  -H "Authorization: Bearer YOUR_API_KEY"

The response returns the Schedule Owner (used as the incident Lead), the Paging Targets (full set the schedule would page), and a currentOncallView with per-layer detail:

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

To check who would be on call at a specific point in time, add an at query parameter with an ISO 8601 datetime:

curl "https://api.scaling.cloud/v1/oncall/schedules/sched_01jqm5x3k8vz9e2f4g7h/resolve?at=2026-04-14T09:00:00.000Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

If entries is empty, no layer is active at the requested time. Check that your layer’s effectiveFrom has passed and that effectiveUntil has not expired.

Get Started

API Guides

Infrastructure as Code

AWS CloudWatch

Inbound Webhooks

MCP Server