Policies

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.cloud 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/policies`

List all escalation policies for your organization. Returns policy metadata only — layers are not included in list responses.

Response fields

data

object[]

required

Array of escalation policy objects.

Show Policy object fields

string

required

Unique policy ID (UUID).

orgId

string

required

The organization this policy belongs to.

name

string

required

Display name of the policy. Unique within your organization.

description

string | null

required

Optional description. null if not set.

createdBy

string

required

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

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

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"
    }
  ]
}

{
  "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 /escalation/policies`

Create 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

name

string

required

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

description

string

Optional description of the policy’s purpose.

Response fields

data

object

required

The created escalation policy.

Show Policy object fields

string

required

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

orgId

string

required

The organization this policy belongs to.

name

string

required

Display name of the policy.

description

string | null

required

Description, or null if not provided.

createdBy

string

required

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

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

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"
  }
}

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

{
  "statusCode": 500,
  "type": "invalid_error",
  "code": "server_error",
  "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.

`GET /escalation/policies/{policyId}`

Retrieve a single escalation policy by ID, including all of its layers ordered by position.

Path parameters

policyId

string

required

The UUID of the policy to retrieve.

Response fields

data

object

required

The policy with its layers.

Show Policy object fields

string

required

Unique policy ID (UUID).

orgId

string

required

The organization this policy belongs to.

name

string

required

Display name of the policy.

description

string | null

required

Description, or null if not set.

createdBy

string

required

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

createdAt

string

required

ISO 8601 creation timestamp.

updatedAt

string

required

ISO 8601 last-updated timestamp.

layers

object[]

required

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"
      }
    ]
  }
}

{
  "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 policy found with the given ID in your organization.
`500`	`server_error`	Unexpected 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

policyId

string

required

The UUID of the policy to update.

Request body

name

string

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

description

string | null

Updated description. Pass null to clear the description.

Response fields

data

object

required

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"
  }
}

{
  "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 policy found with the given ID in your organization.
`500`	`server_error`	Unexpected 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

policyId

string

required

The UUID of the policy to delete.

Response fields

success

boolean

required

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'

{
  "success": true
}

{
  "statusCode": 400,
  "type": "invalid_request_error",
  "code": "policy_in_use",
  "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`	`policy_in_use`	The policy is attached to one or more active incidents and cannot be deleted.
`401`	`not_authorized`	Missing or invalid API key.
`404`	`not_found`	No policy 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 /escalation/policies`

Response fields

Error codes

`POST /escalation/policies`

Request body

Response fields

Error codes

`GET /escalation/policies/{policyId}`

Path parameters

Response fields

Error codes

`PATCH /escalation/policies/{policyId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /escalation/policies/{policyId}`

Path parameters

Response fields

Error codes

​GET /escalation/policies

​Response fields

​Error codes

​POST /escalation/policies

​Request body

​Response fields

​Error codes

​GET /escalation/policies/{policyId}

​Path parameters

​Response fields

​Error codes

​PATCH /escalation/policies/{policyId}

​Path parameters

​Request body

​Response fields

​Error codes

​DELETE /escalation/policies/{policyId}

​Path parameters

​Response fields

​Error codes

`GET /escalation/policies`

Response fields

Error codes

`POST /escalation/policies`

Request body

Response fields

Error codes

`GET /escalation/policies/{policyId}`

Path parameters

Response fields

Error codes

`PATCH /escalation/policies/{policyId}`

Path parameters

Request body

Response fields

Error codes

`DELETE /escalation/policies/{policyId}`

Path parameters

Response fields

Error codes