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 escalation policy defines an ordered sequence of layers, each targeting an on-call schedule or a set of users. When an incident is triggered, Scaling notifies the first layer. If that layer does not acknowledge within ackTimeoutMinutes, it escalates to the next layer.
Policy layers are managed separately. See Policy Layers for endpoints that add, update, reorder, or remove layers from a policy. GET /escalation/policiesList all escalation policies for your organization. Returns policy metadata only — layers are not included in list responses.
Response fields Array of escalation policy objects. Show Policy object fields
The organization this policy belongs to.
Display name of the policy. Unique within your organization.
Optional description. null if not set.
ID of the user or API key that created the policy.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
curl --request GET \ --url https://api.scaling.cloud/v1/escalation/policies \ --header 'Authorization: Bearer scl_live_your_api_key_here'
{ "data" : [ { "id" : "d4e5f6a7-b8c9-0123-defa-234567890123" , "orgId" : "org_2abc123def456" , "name" : "Platform default" , "description" : "Default escalation for all platform incidents" , "createdBy" : "user_9xyz" , "createdAt" : "2026-01-05T08:00:00.000Z" , "updatedAt" : "2026-03-20T16:45:00.000Z" }, { "id" : "e5f6a7b8-c9d0-1234-efab-345678901234" , "orgId" : "org_2abc123def456" , "name" : "Data pipeline critical" , "description" : null , "createdBy" : "user_8wxy" , "createdAt" : "2026-02-14T09:00:00.000Z" , "updatedAt" : "2026-02-14T09:00:00.000Z" } ] }
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 500server_errorUnexpected server error.
POST /escalation/policiesCreate a new escalation policy. The name must be unique within your organization. Add layers separately after creation using POST /escalation/policies/{policyId}/layers.
Request body Display name for the policy. Must be unique within your organization. 1–255 characters.
Optional description of the policy’s purpose.
Response fields The created escalation policy. Show Policy object fields
Unique policy ID (UUID). Stable — never changes after creation.
The organization this policy belongs to.
Display name of the policy.
Description, or null if not provided.
ID of the user or API key that created the policy.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
curl --request POST \ --url https://api.scaling.cloud/v1/escalation/policies \ --header 'Authorization: Bearer scl_live_your_api_key_here' \ --header 'Content-Type: application/json' \ --data '{ "name": "Platform default", "description": "Default escalation for all platform incidents" }'
{ "data" : { "id" : "d4e5f6a7-b8c9-0123-defa-234567890123" , "orgId" : "org_2abc123def456" , "name" : "Platform default" , "description" : "Default escalation for all platform incidents" , "createdBy" : "user_9xyz" , "createdAt" : "2026-04-07T10:00:00.000Z" , "updatedAt" : "2026-04-07T10:00:00.000Z" } }
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 500server_errorUnexpected server error.
GET /escalation/policies/{policyId}Retrieve a single escalation policy by ID, including all of its layers ordered by position.
Path parameters The UUID of the policy to retrieve.
Response fields The policy with its layers. Show Policy object fields
The organization this policy belongs to.
Display name of the policy.
Description, or null if not set.
ID of the user or API key that created the policy.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
Ordered escalation layers. See Policy Layers for field definitions. curl --request GET \ --url https://api.scaling.cloud/v1/escalation/policies/d4e5f6a7-b8c9-0123-defa-234567890123 \ --header 'Authorization: Bearer scl_live_your_api_key_here'
{ "data" : { "id" : "d4e5f6a7-b8c9-0123-defa-234567890123" , "orgId" : "org_2abc123def456" , "name" : "Platform default" , "description" : "Default escalation for all platform incidents" , "createdBy" : "user_9xyz" , "createdAt" : "2026-01-05T08:00:00.000Z" , "updatedAt" : "2026-03-20T16:45:00.000Z" , "layers" : [ { "id" : "f6a7b8c9-d0e1-2345-fabc-456789012345" , "policyId" : "d4e5f6a7-b8c9-0123-defa-234567890123" , "orgId" : "org_2abc123def456" , "position" : 1 , "ackTimeoutMinutes" : 5 , "target" : { "type" : "schedule" , "scheduleId" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "createdAt" : "2026-01-05T08:10:00.000Z" , "updatedAt" : "2026-01-05T08:10:00.000Z" }, { "id" : "a7b8c9d0-e1f2-3456-abcd-567890123456" , "policyId" : "d4e5f6a7-b8c9-0123-defa-234567890123" , "orgId" : "org_2abc123def456" , "position" : 2 , "ackTimeoutMinutes" : 10 , "target" : { "type" : "users" , "userIds" : [ "user_mgr001" , "user_mgr002" ] }, "createdAt" : "2026-01-05T08:12:00.000Z" , "updatedAt" : "2026-01-05T08:12:00.000Z" } ] } }
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 404not_foundNo policy found with the given ID in your organization. 500server_errorUnexpected server error.
PATCH /escalation/policies/{policyId}Update one or more fields on an escalation policy. All fields are optional — only the fields you include are updated. To update layers, use the layer endpoints.
Path parameters The UUID of the policy to update.
Request body New display name for the policy. Must be unique within your organization. 1–255 characters.
Updated description. Pass null to clear the description.
Response fields The updated policy object (metadata only — does not include layers).
curl --request PATCH \ --url https://api.scaling.cloud/v1/escalation/policies/d4e5f6a7-b8c9-0123-defa-234567890123 \ --header 'Authorization: Bearer scl_live_your_api_key_here' \ --header 'Content-Type: application/json' \ --data '{ "description": "Default escalation — platform, infrastructure, and data teams" }'
{ "data" : { "id" : "d4e5f6a7-b8c9-0123-defa-234567890123" , "orgId" : "org_2abc123def456" , "name" : "Platform default" , "description" : "Default escalation — platform, infrastructure, and data teams" , "createdBy" : "user_9xyz" , "createdAt" : "2026-01-05T08:00:00.000Z" , "updatedAt" : "2026-04-07T11:00:00.000Z" } }
Error codes HTTP Code Description 401not_authorizedMissing or invalid API key. 404not_foundNo policy found with the given ID in your organization. 500server_errorUnexpected server error.
DELETE /escalation/policies/{policyId}Delete an escalation policy and all of its layers. This action is permanent.
You cannot delete a policy that is currently attached to one or more active incidents. The request will fail with a 400 policy_in_use error. Resolve or transfer all active incidents using this policy before deleting it.
Path parameters The UUID of the policy to delete.
Response fields true when the policy was deleted.
curl --request DELETE \ --url https://api.scaling.cloud/v1/escalation/policies/d4e5f6a7-b8c9-0123-defa-234567890123 \ --header 'Authorization: Bearer scl_live_your_api_key_here'
200
400 — policy in use
404
Error codes HTTP Code Description 400policy_in_useThe policy is attached to one or more active incidents and cannot be deleted. 401not_authorizedMissing or invalid API key. 404not_foundNo policy found with the given ID in your organization. 500server_errorUnexpected server error.