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.

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

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

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:
FieldDescription
rotationTypeOne of daily, weekly, or custom
rotationLengthDaysNumber of days per rotation shift (minimum 1)
handoffTimeTime of day the rotation switches, in HH:MM 24-hour format
effectiveFromISO 8601 datetime when this layer becomes active
effectiveUntilOptional ISO 8601 datetime when this layer expires; null means it runs indefinitely
participantIdsOrdered 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.
3

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