--- title: "Update On-Call escalation policy" method: PUT path: "/api/v2/on-call/escalation-policies/{policy_id}" tags: ["On-Call"] --- # Update On-Call escalation policy `PUT /api/v2/on-call/escalation-policies/{policy_id}` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` Update an On-Call escalation policy ## Path parameters - `policy_id` string, required ## Query parameters - `include` string ## Request body - EscalationPolicyUpdateRequest: Represents a request to update an existing escalation policy, including the updated policy data. - `data` EscalationPolicyUpdateRequestData, required: Represents the data for updating an existing escalation policy, including its ID, attributes, relationships, and resource type. - `attributes` EscalationPolicyUpdateRequestDataAttributes, required: Defines the attributes that can be updated for an escalation policy, such as description, name, resolution behavior, retries, and steps. - `name` string, required: Specifies the name of the escalation policy. - `resolve_page_on_policy_end` boolean: Indicates whether the page is automatically resolved when the policy ends. - `retries` integer: Specifies how many times the escalation sequence is retried if there is no response. - `steps` EscalationPolicyUpdateRequestDataAttributesStepsItems[], required: A list of escalation steps, each defining assignment, escalation timeout, and targets. - `assignment` 'default' | 'round-robin': Specifies how this escalation step will assign targets (example `default` or `round-robin`). - `escalate_after_seconds` integer: Defines how many seconds to wait before escalating to the next step. - `id` string: Specifies the unique identifier of this step. - `targets` EscalationPolicyStepTarget[], required: Specifies the collection of escalation targets for this step. - `config` EscalationPolicyStepTargetConfig: Configuration for an escalation target, such as schedule position. - `schedule` EscalationPolicyStepTargetConfigSchedule: Schedule-specific configuration for an escalation target. - … - `id` string: Specifies the unique identifier for this target. - `type` 'users' | 'schedules' | 'teams': Specifies the type of escalation target (example `users`, `schedules`, or `teams`). - `id` string, required: Specifies the unique identifier of the escalation policy being updated. - `relationships` EscalationPolicyUpdateRequestDataRelationships: Represents relationships in an escalation policy update request, including references to teams. - `teams` DataRelationshipsTeams: Associates teams with this schedule in a data structure. - `data` DataRelationshipsTeamsDataItems[]: An array of team references for this schedule. - `id` string, required: The unique identifier of the team in this relationship. - `type` 'teams', required: Teams resource type. - `type` 'policies', required: Indicates that the resource is of type `policies`. ## Response `200` OK - EscalationPolicy: Represents a complete escalation policy response, including policy data and optionally included related resources. - `data` EscalationPolicyData: Represents the data for a single escalation policy, including its attributes, ID, relationships, and resource type. - `attributes` EscalationPolicyDataAttributes: Defines the main attributes of an escalation policy, such as its name and behavior on policy end. - `name` string, required: Specifies the name of the escalation policy. - `resolve_page_on_policy_end` boolean: Indicates whether the page is automatically resolved when the policy ends. - `retries` integer: Specifies how many times the escalation sequence is retried if there is no response. - `id` string: Specifies the unique identifier of the escalation policy. - `relationships` EscalationPolicyDataRelationships: Represents the relationships for an escalation policy, including references to steps and teams. - `steps` EscalationPolicyDataRelationshipsSteps, required: Defines the relationship to a collection of steps within an escalation policy. Contains an array of step data references. - `data` EscalationPolicyDataRelationshipsStepsDataItems[]: An array of references to the steps defined in this escalation policy. - `id` string, required: Specifies the unique identifier for the step resource. - `type` 'steps', required: Indicates that the resource is of type `steps`. - `teams` DataRelationshipsTeams: Associates teams with this schedule in a data structure. - `data` DataRelationshipsTeamsDataItems[]: An array of team references for this schedule. - `id` string, required: The unique identifier of the team in this relationship. - `type` 'teams', required: Teams resource type. - `type` 'policies', required: Indicates that the resource is of type `policies`. - `included` EscalationPolicyIncluded[]: Provides any included related resources, such as steps or targets, returned with the policy. - union: Represents included related resources when retrieving an escalation policy, such as teams, steps, or targets. - EscalationPolicyStep: Represents a single step in an escalation policy, including its attributes, relationships, and resource type. - `attributes` EscalationPolicyStepAttributes: Defines attributes for an escalation policy step, such as assignment strategy and escalation timeout. - `assignment` 'default' | 'round-robin': Specifies how this escalation step will assign targets (example `default` or `round-robin`). - `escalate_after_seconds` integer: Specifies how many seconds to wait before escalating to the next step. - `id` string: Specifies the unique identifier of this escalation policy step. - `relationships` EscalationPolicyStepRelationships: Represents the relationship of an escalation policy step to its targets. - `targets` EscalationTargets: A list of escalation targets for a step - `data` EscalationTarget[]: The `EscalationTargets` `data`. - … - `type` 'steps', required: Indicates that the resource is of type `steps`. - EscalationPolicyUser: Represents a user object in the context of an escalation policy, including their `id`, type, and basic attributes. - `attributes` EscalationPolicyUserAttributes: Provides basic user information for an escalation policy, including a name and email address. - `email` string: The user's email address. - `name` string: The user's name. - `status` 'active' | 'deactivated' | 'pending': The user's status. - `id` string: The unique user identifier. - `type` 'users', required: Users resource type. - ScheduleData: Represents the primary data object for a schedule, linking attributes and relationships. - `attributes` ScheduleDataAttributes: Provides core properties of a schedule object such as its name and time zone. - `name` string: A short name for the schedule. - `time_zone` string: The time zone in which this schedule operates. - `id` string: The schedule's unique identifier. - `relationships` ScheduleDataRelationships: Groups the relationships for a schedule object, referencing layers and teams. - `layers` ScheduleDataRelationshipsLayers: Associates layers with this schedule in a data structure. - `data` ScheduleDataRelationshipsLayersDataItems[]: An array of layer references for this schedule. - … - `teams` DataRelationshipsTeams: Associates teams with this schedule in a data structure. - `data` DataRelationshipsTeamsDataItems[]: An array of team references for this schedule. - … - `type` 'schedules', required: Schedules resource type. - ConfiguredSchedule: Full resource representation of a configured schedule target with position (previous, current, or next). - `attributes` ConfiguredScheduleTargetAttributes, required: Attributes for a configured schedule target, including position. - `position` 'previous' | 'current' | 'next', required: Specifies the position of a schedule target (example `previous`, `current`, or `next`). - `id` string, required: Specifies the unique identifier of the configured schedule target. - `relationships` ConfiguredScheduleTargetRelationships, required: Represents the relationships of a configured schedule target. - `schedule` ConfiguredScheduleTargetRelationshipsSchedule, required: Holds the schedule reference for a configured schedule target. - `data` ScheduleTarget, required: Represents a schedule target for an escalation policy step, including its ID and resource type. This is a shortcut for a configured schedule target with position set to 'current'. - … - `type` 'schedule_target', required: Indicates that the resource is of type `schedule_target`. - TeamReference: Provides a reference to a team, including ID, type, and basic attributes/relationships. - `attributes` TeamReferenceAttributes: Encapsulates the basic attributes of a Team reference, such as name, handle, and an optional avatar or description. - `avatar` string: URL or reference for the team's avatar (if available). - `description` string: A short text describing the team. - `handle` string: A unique handle/slug for the team. - `name` string: The full, human-readable name of the team. - `id` string: The team's unique identifier. - `type` 'teams', required: Teams resource type. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `429`: Too many requests --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)