Schedules

An on-call schedule defines a named rotation with a timezone. Rotation layers attached to a schedule determine who is on call at any given time. Use these endpoints to manage schedule metadata and resolve the current on-call responder.

Layers are managed separately. See Rotation Layers for endpoints that add, update, or remove rotation layers from a schedule.

`GET /oncall/schedules`

List all on-call schedules for your organization. Returns schedule metadata only — to include rotation layers, fetch an individual schedule with GET /oncall/schedules/{scheduleId}.

Response fields

data

object[]

required

Array of schedule objects.

Show Schedule object fields

string

required

Unique schedule ID (UUID).

orgId

string

required

The organization this schedule belongs to.

name

string

required

Display name of the schedule. Unique within your organization.

description

string | null

required

Optional description. null if not set.

timezone

string

required

IANA timezone identifier, e.g. America/New_York.

createdBy

string

required

ID of the user or API key that created the schedule.

createdAt

string

required

ISO 8601 timestamp of when the schedule was created.

updatedAt

string

required

ISO 8601 timestamp of the last update.

curl --request GET \
  --url https://api.scaling.cloud/v1/oncall/schedules \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "org_2abc123def456",
      "name": "Platform On-call",
      "description": "Primary rotation for the platform engineering team",
      "timezone": "America/New_York",
      "createdBy": "user_9xyz",
      "createdAt": "2026-01-01T09:00:00.000Z",
      "updatedAt": "2026-03-15T14:22:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "orgId": "org_2abc123def456",
      "name": "Data Infrastructure On-call",
      "description": null,
      "timezone": "America/Los_Angeles",
      "createdBy": "user_8wxy",
      "createdAt": "2026-02-10T11:30:00.000Z",
      "updatedAt": "2026-02-10T11:30:00.000Z"
    }
  ]
}

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`500`	`server_error`	Unexpected server error.

`POST /oncall/schedules`

Create a new on-call schedule for your organization. The name must be unique within your org.

Request body

name

string

required

Display name for the schedule. Must be unique within your organization. 1–255 characters.

description

string

Optional description of the schedule’s purpose.

timezone

string

required

IANA timezone identifier for the schedule, e.g. America/Chicago. All rotation layer handoff times are interpreted in this timezone.

Response fields

data

object

required

The created schedule object.

Show Schedule object fields

string

required

Unique schedule ID (UUID). Stable — never changes after creation.

orgId

string

required

The organization this schedule belongs to.

name

string

required

Display name of the schedule.

description

string | null

required

Description, or null if not provided.

timezone

string

required

IANA timezone identifier.

createdBy

string

required

ID of the user or API key that created the schedule.

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last-updated timestamp.

curl --request POST \
  --url https://api.scaling.cloud/v1/oncall/schedules \
  --header 'Authorization: Bearer scl_live_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Platform On-call",
    "description": "Primary rotation for the platform engineering team",
    "timezone": "America/New_York"
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123def456",
    "name": "Platform On-call",
    "description": "Primary rotation for the platform engineering team",
    "timezone": "America/New_York",
    "createdBy": "user_9xyz",
    "createdAt": "2026-04-07T10:00:00.000Z",
    "updatedAt": "2026-04-07T10:00:00.000Z"
  }
}

{
  "statusCode": 400,
  "type": "invalid_request_error",
  "code": "invalid_timezone",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "statusCode": 401,
  "type": "not_authorized_error",
  "code": "not_authorized",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`400`	`invalid_timezone`	`timezone` is not a valid IANA timezone identifier.
`401`	`not_authorized`	Missing or invalid API key.
`500`	`server_error`	Unexpected server error.

`GET /oncall/schedules/{scheduleId}`

Retrieve a single schedule by ID, including all of its rotation layers.

Path parameters

scheduleId

string

required

The UUID of the schedule to retrieve.

Response fields

data

object

required

The schedule object with its rotation layers.

Show Schedule object fields

string

required

Unique schedule ID (UUID).

orgId

string

required

The organization this schedule belongs to.

name

string

required

Display name of the schedule.

description

string | null

required

Description, or null if not set.

timezone

string

required

IANA timezone identifier.

createdBy

string

required

ID of the user or API key that created the schedule.

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last-updated timestamp.

layers

object[]

required

Rotation layers attached to this schedule. See Rotation Layers for field definitions.

curl --request GET \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123def456",
    "name": "Platform On-call",
    "description": "Primary rotation for the platform engineering team",
    "timezone": "America/New_York",
    "createdBy": "user_9xyz",
    "createdAt": "2026-01-01T09:00:00.000Z",
    "updatedAt": "2026-03-15T14:22:00.000Z",
    "layers": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "scheduleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "orgId": "org_2abc123def456",
        "name": "Primary rotation",
        "rotationType": "weekly",
        "rotationLengthDays": 7,
        "handoffTime": "09:00",
        "effectiveFrom": "2026-01-01T00:00:00.000Z",
        "effectiveUntil": null,
        "participantIds": ["user_aaa111", "user_bbb222", "user_ccc333"],
        "createdAt": "2026-01-01T09:05:00.000Z",
        "updatedAt": "2026-01-01T09:05:00.000Z"
      }
    ]
  }
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No schedule found with the given ID in your organization.
`500`	`server_error`	Unexpected server error.

`PATCH /oncall/schedules/{scheduleId}`

Update one or more fields on a schedule. All fields are optional — only the fields you include are updated.

Path parameters

scheduleId

string

required

The UUID of the schedule to update.

Request body

name

string

New display name for the schedule. Must be unique within your organization. 1–255 characters.

description

string | null

Updated description. Pass null to clear the description.

timezone

string

New IANA timezone identifier. Changing the timezone affects how all existing rotation layer handoff times are interpreted.

Response fields

data

object

required

The updated schedule object (metadata only — does not include layers).

curl --request PATCH \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header 'Authorization: Bearer scl_live_your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Primary rotation — platform and infrastructure teams",
    "timezone": "America/Chicago"
  }'

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123def456",
    "name": "Platform On-call",
    "description": "Primary rotation — platform and infrastructure teams",
    "timezone": "America/Chicago",
    "createdBy": "user_9xyz",
    "createdAt": "2026-01-01T09:00:00.000Z",
    "updatedAt": "2026-04-07T10:30:00.000Z"
  }
}

{
  "statusCode": 400,
  "type": "invalid_request_error",
  "code": "invalid_timezone",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`400`	`invalid_timezone`	`timezone` is not a valid IANA timezone identifier.
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No schedule found with the given ID in your organization.
`500`	`server_error`	Unexpected server error.

`DELETE /oncall/schedules/{scheduleId}`

Delete a schedule and all of its rotation layers. This action is permanent and cannot be undone.

Path parameters

scheduleId

string

required

The UUID of the schedule to delete.

Response fields

success

boolean

required

true when the schedule was deleted.

curl --request DELETE \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

{
  "success": true
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No schedule found with the given ID in your organization.
`500`	`server_error`	Unexpected server error.

`GET /oncall/schedules/{scheduleId}/resolve`

Resolve who is currently on call for a schedule. Returns three views in one response: the Schedule Owner (a single user for the incident Lead), the Paging Targets (the full set of users an escalation policy targeting this schedule would page), and the Current On-call View (a richer, position-ordered breakdown including override provenance). By default this returns the resolution at the current time. Pass the optional at query parameter to resolve at a specific moment. The Schedule Owner is the lowest-positioned currently-active rotation layer’s resolved participant — with the schedule’s active override applied if one is in effect. If position 0 is between effective windows, owner resolution falls through to the next-lowest position.

Path parameters

scheduleId

string

required

The UUID of the schedule to query.

Query parameters

string

ISO 8601 datetime to resolve on-call for. Defaults to the current server time if omitted. Example: 2026-06-15T14:00:00.000Z.

Response fields

data

object

required

The on-call resolution result.

Show Resolution fields

owner

object | null

required

The Schedule Owner — null if no rotation layer resolves to a user at the requested time. Populated as the incident Lead when an incident is created against this schedule.

pagingTargets

object[]

required

Users to page when an escalation policy layer targets this schedule. One entry per currently-active rotation layer in position order, with each entry’s override applied if active.

currentOncallView

object

required

Full reduced view of the schedule at resolvedAt.

Show Current on-call view fields

scheduleId

string

required

The schedule ID that was resolved.

resolvedAt

string

required

ISO 8601 timestamp of the point in time that was resolved (either now or the value of at).

owner

object | null

required

Same Schedule Owner as the top-level owner. Repeated here so callers that only consume currentOncallView get the full picture.

entries

object[]

required

One entry per currently-active rotation layer, ordered by position ascending. Empty if no layer is active.

Show Entry fields

rotationLayerId

string

required

ID of the rotation layer that produced this entry.

rotationLayerName

string

required

Name of the rotation layer.

position

integer

required

The layer’s position within the schedule. Lower = higher precedence; position 0 is the owner-bearing layer.

user

object

required

The user currently on-call for this layer — the override user if source is override, otherwise the resolved rotation participant.

source

string

required

Either rotation (the layer’s rotation produced this entry) or override (an active override substituted in for this layer).

overriddenUser

object

Only present when source is override. The rotation participant the override displaced.

viaOverrideId

string

Only present when source is override. The ID of the override row producing this entry.

curl --request GET \
  --url https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resolve \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

curl --request GET \
  --url 'https://api.scaling.cloud/v1/oncall/schedules/a1b2c3d4-e5f6-7890-abcd-ef1234567890/resolve?at=2026-06-15T14%3A00%3A00.000Z' \
  --header 'Authorization: Bearer scl_live_your_api_key_here'

{
  "data": {
    "owner": {
      "user": {
        "id": "user_bbb222",
        "firstName": "Alice",
        "lastName": "Chen",
        "email": "alice@acme.io"
      }
    },
    "pagingTargets": [
      {
        "user": {
          "id": "user_bbb222",
          "firstName": "Alice",
          "lastName": "Chen",
          "email": "alice@acme.io"
        }
      },
      {
        "user": {
          "id": "user_ccc333",
          "firstName": "Bob",
          "lastName": "Martinez",
          "email": "bob@acme.io"
        }
      }
    ],
    "currentOncallView": {
      "scheduleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resolvedAt": "2026-04-07T10:00:00.000Z",
      "owner": {
        "user": {
          "id": "user_bbb222",
          "firstName": "Alice",
          "lastName": "Chen",
          "email": "alice@acme.io"
        }
      },
      "entries": [
        {
          "rotationLayerId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "rotationLayerName": "Primary",
          "position": 0,
          "user": {
            "id": "user_bbb222",
            "firstName": "Alice",
            "lastName": "Chen",
            "email": "alice@acme.io"
          },
          "source": "rotation"
        },
        {
          "rotationLayerId": "d4e5f6a7-b8c9-0123-defa-2345678901234",
          "rotationLayerName": "Secondary",
          "position": 1,
          "user": {
            "id": "user_ccc333",
            "firstName": "Bob",
            "lastName": "Martinez",
            "email": "bob@acme.io"
          },
          "source": "rotation"
        }
      ]
    }
  }
}

{
  "data": {
    "owner": {
      "user": {
        "id": "user_eee555",
        "firstName": "Eve",
        "lastName": "Nguyen",
        "email": "eve@acme.io"
      }
    },
    "pagingTargets": [
      {
        "user": {
          "id": "user_eee555",
          "firstName": "Eve",
          "lastName": "Nguyen",
          "email": "eve@acme.io"
        }
      }
    ],
    "currentOncallView": {
      "scheduleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resolvedAt": "2026-04-15T10:00:00.000Z",
      "owner": {
        "user": {
          "id": "user_eee555",
          "firstName": "Eve",
          "lastName": "Nguyen",
          "email": "eve@acme.io"
        }
      },
      "entries": [
        {
          "rotationLayerId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "rotationLayerName": "Primary",
          "position": 0,
          "user": {
            "id": "user_eee555",
            "firstName": "Eve",
            "lastName": "Nguyen",
            "email": "eve@acme.io"
          },
          "source": "override",
          "overriddenUser": {
            "id": "user_bbb222",
            "firstName": "Alice",
            "lastName": "Chen",
            "email": "alice@acme.io"
          },
          "viaOverrideId": "f7a8b9c0-d1e2-3456-fab7-89cdef012345"
        }
      ]
    }
  }
}

{
  "data": {
    "owner": null,
    "pagingTargets": [],
    "currentOncallView": {
      "scheduleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "resolvedAt": "2025-12-01T03:00:00.000Z",
      "owner": null,
      "entries": []
    }
  }
}

{
  "statusCode": 404,
  "type": "invalid_request_error",
  "code": "not_found",
  "requestId": "550e8400-e29b-41d4-a716-446655440000"
}

Error codes

HTTP	Code	Description
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No schedule found with the given ID in your organization.
`500`	`server_error`	Unexpected server error.

Overview

Incidents

On-call Schedules

Escalation Policies

Routing Policies

Working Hours

Team

`GET /oncall/schedules`

Response fields

Error codes

`POST /oncall/schedules`

Request body

Response fields

Error codes

`GET /oncall/schedules/{scheduleId}`

Path parameters

Response fields

Error codes

`PATCH /oncall/schedules/{scheduleId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /oncall/schedules/{scheduleId}`

Path parameters

Response fields

Error codes

`GET /oncall/schedules/{scheduleId}/resolve`

Path parameters

Query parameters

Response fields

Error codes

​GET /oncall/schedules

​Response fields

​Error codes

​POST /oncall/schedules

​Request body

​Response fields

​Error codes

​GET /oncall/schedules/{scheduleId}

​Path parameters

​Response fields

​Error codes

​PATCH /oncall/schedules/{scheduleId}

​Path parameters

​Request body

​Response fields

​Error codes

​DELETE /oncall/schedules/{scheduleId}

​Path parameters

​Response fields

​Error codes

​GET /oncall/schedules/{scheduleId}/resolve

​Path parameters

​Query parameters

​Response fields

​Error codes

`GET /oncall/schedules`

Response fields

Error codes

`POST /oncall/schedules`

Request body

Response fields

Error codes

`GET /oncall/schedules/{scheduleId}`

Path parameters

Response fields

Error codes

`PATCH /oncall/schedules/{scheduleId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /oncall/schedules/{scheduleId}`

Path parameters

Response fields

Error codes

`GET /oncall/schedules/{scheduleId}/resolve`

Path parameters

Query parameters

Response fields

Error codes