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 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/schedulesList 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 Array of schedule objects. Show Schedule object fields
Unique schedule ID (UUID).
The organization this schedule belongs to.
Display name of the schedule. Unique within your organization.
Optional description. null if not set.
IANA timezone identifier, e.g. America/New_York.
ID of the user or API key that created the schedule.
ISO 8601 timestamp of when the schedule was created.
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" } ] }
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 500server_errorUnexpected server error.
POST /oncall/schedulesCreate a new on-call schedule for your organization. The name must be unique within your org.
Request body Display name for the schedule. Must be unique within your organization. 1–255 characters.
Optional description of the schedule’s purpose.
IANA timezone identifier for the schedule, e.g. America/Chicago. All rotation layer handoff times are interpreted in this timezone.
Response fields The created schedule object. Show Schedule object fields
Unique schedule ID (UUID). Stable — never changes after creation.
The organization this schedule belongs to.
Display name of the schedule.
Description, or null if not provided.
IANA timezone identifier.
ID of the user or API key that created the schedule.
ISO 8601 creation timestamp.
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" } }
Error codes HTTP Code Description 400invalid_timezonetimezone is not a valid IANA timezone identifier.401not_authorizedMissing or invalid API key. 500server_errorUnexpected server error.
GET /oncall/schedules/{scheduleId}Retrieve a single schedule by ID, including all of its rotation layers.
Path parameters The UUID of the schedule to retrieve.
Response fields The schedule object with its rotation layers. Show Schedule object fields
Unique schedule ID (UUID).
The organization this schedule belongs to.
Display name of the schedule.
Description, or null if not set.
IANA timezone identifier.
ID of the user or API key that created the schedule.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
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" } ] } }
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 404not_foundNo schedule found with the given ID in your organization. 500server_errorUnexpected 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 The UUID of the schedule to update.
Request body New display name for the schedule. Must be unique within your organization. 1–255 characters.
Updated description. Pass null to clear the description.
New IANA timezone identifier. Changing the timezone affects how all existing rotation layer handoff times are interpreted.
Response fields 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" } }
Error codes HTTP Code Description 400invalid_timezonetimezone is not a valid IANA timezone identifier.401not_authorizedMissing or invalid API key. 404not_foundNo schedule found with the given ID in your organization. 500server_errorUnexpected 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 The UUID of the schedule to delete.
Response fields 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'
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 404not_foundNo schedule found with the given ID in your organization. 500server_errorUnexpected server error.
GET /oncall/schedules/{scheduleId}/resolveResolve who is currently on call for a schedule. Returns three views in one response: the Schedule Owner (a single user for Incident.ownerId), 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 The UUID of the schedule to query.
Query parameters 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 The on-call resolution result. The Schedule Owner — null if no rotation layer resolves to a user at the requested time. Populated into Incident.ownerId when an incident is created against this schedule.
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.
Full reduced view of the schedule at resolvedAt. Show Current on-call view fields
The schedule ID that was resolved.
ISO 8601 timestamp of the point in time that was resolved (either now or the value of at).
Same Schedule Owner as the top-level owner. Repeated here so callers that only consume currentOncallView get the full picture.
One entry per currently-active rotation layer, ordered by position ascending. Empty if no layer is active. ID of the rotation layer that produced this entry.
Name of the rotation layer.
The layer’s position within the schedule. Lower = higher precedence; position 0 is the owner-bearing layer.
The user currently on-call for this layer — the override user if source is override, otherwise the resolved rotation participant.
Either rotation (the layer’s rotation produced this entry) or override (an active override substituted in for this layer).
Only present when source is override. The rotation participant the override displaced.
Only present when source is override. The ID of the override row producing this entry.
cURL — current on-call
cURL — on-call at a specific time
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'
200
200 — override active on position 0
200 — no active layer
404
{ "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" } ] } } }
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 404not_foundNo schedule found with the given ID in your organization. 500server_errorUnexpected server error.