Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 US1-FED

On-Call

Configure your Datadog On-Call directly through the Datadog API.

Create on-call schedule

POST https://api.ap1.datadoghq.com/api/v2/on-call/scheduleshttps://api.datadoghq.eu/api/v2/on-call/scheduleshttps://api.ddog-gov.com/api/v2/on-call/scheduleshttps://api.datadoghq.com/api/v2/on-call/scheduleshttps://api.us3.datadoghq.com/api/v2/on-call/scheduleshttps://api.us5.datadoghq.com/api/v2/on-call/schedules

Overview

Create a new on-call schedule

Arguments

Query Strings

Name

Type

Description

include

string

Comma-separated list of included relationships to be returned. Allowed values: teams, layers, layers.members, layers.members.user.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

The core data wrapper for creating a schedule, encompassing attributes, relationships, and the resource type.

attributes

object

Describes the main attributes for creating a new schedule, including name, layers, time zone, and tags.

layers [required]

[object]

The layers of on-call coverage that define rotation intervals and restrictions.

effective_date [required]

date-time

The date/time when this layer becomes active (in ISO 8601).

end_date

date-time

The date/time after which this layer no longer applies (in ISO 8601).

interval [required]

object

Defines how frequently the rotation repeats, using days and/or seconds (up to certain limits).

days

int32

The number of full days in each rotation period.

seconds

int64

Extra seconds that may be added to extend the rotation beyond whole days.

members [required]

[object]

A list of members who participate in this layer's rotation.

user

object

Identifies the user participating in this layer as a single object with an id.

id

string

The user's ID.

name [required]

string

The name of this layer.

restrictions

[object]

Zero or more time-based restrictions (for example, only weekdays, during business hours).

end_day

enum

The weekday when the restriction period ends (Monday through Sunday). Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

end_time

string

The time of day when the restriction ends (hh:mm:ss).

start_day

enum

The weekday when the restriction period starts (Monday through Sunday). Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

start_time

string

The time of day when the restriction begins (hh:mm:ss).

rotation_start [required]

date-time

The date/time when the rotation for this layer starts (in ISO 8601).

name [required]

string

A human-readable name for the new schedule.

tags

[string]

A list of tags for categorizing or filtering the schedule.

time_zone [required]

string

The time zone in which the schedule is defined.

relationships

object

Gathers relationship objects for the schedule creation request, including the teams to associate.

teams

object

Associates the new schedule with one or more teams.

data

[object]

An array of team references for this schedule.

id [required]

string

A unique identifier for the team.

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

type [required]

enum

Schedules resource type. Allowed enum values: schedules

default: schedules

{
  "data": {
    "attributes": {
      "layers": [
        {
          "effective_date": "2021-11-01T11:11:11+00:00",
          "end_date": "2021-11-21T11:11:11+00:00",
          "interval": {
            "days": 1
          },
          "members": [
            {
              "user": {
                "id": "string"
              }
            }
          ],
          "name": "Layer 1",
          "restrictions": [
            {
              "end_day": "friday",
              "end_time": "17:00:00",
              "start_day": "monday",
              "start_time": "09:00:00"
            }
          ],
          "rotation_start": "2021-11-06T11:11:11+00:00"
        }
      ],
      "name": "Example-On-Call",
      "tags": [
        "tag1",
        "tag2"
      ],
      "time_zone": "America/New_York"
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "teams"
          }
        ]
      }
    },
    "type": "schedules"
  }
}

Response

Created

Top-level container for a schedule object, including both the data payload and any related included resources (such as teams, layers, or members).

Expand All

Field

Type

Description

data

object

Represents the primary data object for a schedule, linking attributes and relationships.

attributes

object

Provides core properties of a schedule object, such as its name, time zone, and tags.

name

string

A short name for the schedule.

tags

[string]

A list of tags associated with this schedule.

time_zone

string

The time zone in which this schedule operates.

id

string

The schedule's unique identifier.

relationships

object

Groups the relationships for a schedule object, referencing layers and teams.

layers

object

Associates layers with this schedule in a data structure.

data

[object]

An array of layer references for this schedule.

id [required]

string

The unique identifier of the layer in this relationship.

type [required]

enum

Layers resource type. Allowed enum values: layers

default: layers

teams

object

Associates teams with this schedule in a data structure.

data

[object]

An array of team references for this schedule.

id [required]

string

The unique identifier of the team in this relationship.

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

type [required]

enum

Schedules resource type. Allowed enum values: schedules

default: schedules

included

[ <oneOf>]

Any additional resources related to this schedule, such as teams and layers.

Option 1

object

Provides a reference to a team, including ID, type, and basic attributes/relationships.

attributes

object

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.

relationships

object

Collects the key relationship fields for a team reference, specifically on-call users.

oncall_users

object

Defines which users are on-call within a team, stored as an array of references.

data

[object]

The list of user references who are on-call for this team.

id [required]

string

The unique identifier of the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

Option 2

object

Encapsulates a layer resource, holding attributes like rotation details, plus relationships to the members covering that layer.

attributes

object

Describes key properties of a Layer, including rotation details, name, start/end times, and any restrictions.

effective_date

date-time

When the layer becomes active (ISO 8601).

end_date

date-time

When the layer ceases to be active (ISO 8601).

interval

object

Defines how often the rotation repeats, using a combination of days and optional seconds.

days

int32

The number of days in each rotation cycle.

seconds

int64

Any additional seconds for the rotation cycle (up to 30 days).

name

string

The name of this layer.

restrictions

[object]

An optional list of time restrictions for when this layer is in effect.

end_day

enum

Defines the end day of the restriction within a Layer. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

end_time

string

The time of day the restriction ends (hh:mm:ss).

start_day

enum

Defines the start day of the restriction within a Layer. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

start_time

string

The time of day the restriction begins (hh:mm:ss).

rotation_start

date-time

The date/time when the rotation starts (ISO 8601).

id

string

A unique identifier for this layer.

relationships

object

Holds references to objects related to the Layer entity, such as its members.

members

object

Holds an array of references to the members of a Layer, each containing member IDs.

data

[object]

The list of members who belong to this layer.

id [required]

string

The unique user ID of the layer member.

type [required]

enum

Members resource type. Allowed enum values: members

default: members

type [required]

enum

Layers resource type. Allowed enum values: layers

default: layers

Option 3

object

Represents a single member entry in a schedule, referencing a specific user.

id

string

The unique identifier for this schedule member.

relationships

object

Defines relationships for a schedule member, primarily referencing a single user.

user

object

Wraps the user data reference for a schedule member.

data [required]

object

Points to the user data associated with this schedule member, including an ID and type.

id [required]

string

The user's unique identifier.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Schedule Members resource type. Allowed enum values: members

default: members

Option 4

object

Represents a user object in the context of a schedule, including their id, type, and basic attributes.

attributes

object

Provides basic user information for a schedule, including a name and email address.

email

string

The user's email address.

name

string

The user's name.

id

string

The unique user identifier.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

{
  "data": {
    "attributes": {
      "name": "Primary On-Call",
      "tags": [],
      "time_zone": "America/New_York"
    },
    "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
    "relationships": {
      "layers": {
        "data": [
          {
            "id": "00000000-0000-0000-0000-000000000001",
            "type": "layers"
          }
        ]
      },
      "teams": {
        "data": [
          {
            "id": "00000000-da3a-0000-0000-000000000000",
            "type": "teams"
          }
        ]
      }
    },
    "type": "schedules"
  },
  "included": []
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

"""
Create on-call schedule returns "Created" response
"""

from datetime import datetime
from dateutil.relativedelta import relativedelta
from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.on_call_api import OnCallApi
from datadog_api_client.v2.model.schedule_create_request import ScheduleCreateRequest
from datadog_api_client.v2.model.schedule_create_request_data import ScheduleCreateRequestData
from datadog_api_client.v2.model.schedule_create_request_data_attributes import ScheduleCreateRequestDataAttributes
from datadog_api_client.v2.model.schedule_create_request_data_attributes_layers_items import (
    ScheduleCreateRequestDataAttributesLayersItems,
)
from datadog_api_client.v2.model.schedule_create_request_data_attributes_layers_items_interval import (
    ScheduleCreateRequestDataAttributesLayersItemsInterval,
)
from datadog_api_client.v2.model.schedule_create_request_data_attributes_layers_items_members_items import (
    ScheduleCreateRequestDataAttributesLayersItemsMembersItems,
)
from datadog_api_client.v2.model.schedule_create_request_data_attributes_layers_items_members_items_user import (
    ScheduleCreateRequestDataAttributesLayersItemsMembersItemsUser,
)
from datadog_api_client.v2.model.schedule_create_request_data_attributes_layers_items_restrictions_items import (
    ScheduleCreateRequestDataAttributesLayersItemsRestrictionsItems,
)
from datadog_api_client.v2.model.schedule_create_request_data_attributes_layers_items_restrictions_items_end_day import (
    ScheduleCreateRequestDataAttributesLayersItemsRestrictionsItemsEndDay,
)
from datadog_api_client.v2.model.schedule_create_request_data_attributes_layers_items_restrictions_items_start_day import (
    ScheduleCreateRequestDataAttributesLayersItemsRestrictionsItemsStartDay,
)
from datadog_api_client.v2.model.schedule_create_request_data_relationships import (
    ScheduleCreateRequestDataRelationships,
)
from datadog_api_client.v2.model.schedule_create_request_data_relationships_teams import (
    ScheduleCreateRequestDataRelationshipsTeams,
)
from datadog_api_client.v2.model.schedule_create_request_data_relationships_teams_data_items import (
    ScheduleCreateRequestDataRelationshipsTeamsDataItems,
)
from datadog_api_client.v2.model.schedule_create_request_data_relationships_teams_data_items_type import (
    ScheduleCreateRequestDataRelationshipsTeamsDataItemsType,
)
from datadog_api_client.v2.model.schedule_create_request_data_type import ScheduleCreateRequestDataType

# there is a valid "user" in the system
USER_DATA_ID = environ["USER_DATA_ID"]

# there is a valid "team" in the system
TEAM_DATA_ID = environ["TEAM_DATA_ID"]

body = ScheduleCreateRequest(
    data=ScheduleCreateRequestData(
        attributes=ScheduleCreateRequestDataAttributes(
            layers=[
                ScheduleCreateRequestDataAttributesLayersItems(
                    effective_date=(datetime.now() + relativedelta(days=-10)),
                    end_date=(datetime.now() + relativedelta(days=10)),
                    interval=ScheduleCreateRequestDataAttributesLayersItemsInterval(
                        days=1,
                    ),
                    members=[
                        ScheduleCreateRequestDataAttributesLayersItemsMembersItems(
                            user=ScheduleCreateRequestDataAttributesLayersItemsMembersItemsUser(
                                id=USER_DATA_ID,
                            ),
                        ),
                    ],
                    name="Layer 1",
                    restrictions=[
                        ScheduleCreateRequestDataAttributesLayersItemsRestrictionsItems(
                            end_day=ScheduleCreateRequestDataAttributesLayersItemsRestrictionsItemsEndDay.FRIDAY,
                            end_time="17:00:00",
                            start_day=ScheduleCreateRequestDataAttributesLayersItemsRestrictionsItemsStartDay.MONDAY,
                            start_time="09:00:00",
                        ),
                    ],
                    rotation_start=(datetime.now() + relativedelta(days=-5)),
                ),
            ],
            name="Example-On-Call",
            tags=[
                "tag1",
                "tag2",
            ],
            time_zone="America/New_York",
        ),
        relationships=ScheduleCreateRequestDataRelationships(
            teams=ScheduleCreateRequestDataRelationshipsTeams(
                data=[
                    ScheduleCreateRequestDataRelationshipsTeamsDataItems(
                        id=TEAM_DATA_ID,
                        type=ScheduleCreateRequestDataRelationshipsTeamsDataItemsType.TEAMS,
                    ),
                ],
            ),
        ),
        type=ScheduleCreateRequestDataType.SCHEDULES,
    ),
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = OnCallApi(api_client)
    response = api_instance.create_on_call_schedule(body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"

Get on-call schedule

GET https://api.ap1.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.datadoghq.eu/api/v2/on-call/schedules/{schedule_id}https://api.ddog-gov.com/api/v2/on-call/schedules/{schedule_id}https://api.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.us3.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.us5.datadoghq.com/api/v2/on-call/schedules/{schedule_id}

Overview

Get an on-call schedule

Arguments

Path Parameters

Name

Type

Description

schedule_id [required]

string

The ID of the schedule

Query Strings

Name

Type

Description

include

string

Comma-separated list of included relationships to be returned. Allowed values: teams, layers, layers.members, layers.members.user.

Response

OK

Top-level container for a schedule object, including both the data payload and any related included resources (such as teams, layers, or members).

Expand All

Field

Type

Description

data

object

Represents the primary data object for a schedule, linking attributes and relationships.

attributes

object

Provides core properties of a schedule object, such as its name, time zone, and tags.

name

string

A short name for the schedule.

tags

[string]

A list of tags associated with this schedule.

time_zone

string

The time zone in which this schedule operates.

id

string

The schedule's unique identifier.

relationships

object

Groups the relationships for a schedule object, referencing layers and teams.

layers

object

Associates layers with this schedule in a data structure.

data

[object]

An array of layer references for this schedule.

id [required]

string

The unique identifier of the layer in this relationship.

type [required]

enum

Layers resource type. Allowed enum values: layers

default: layers

teams

object

Associates teams with this schedule in a data structure.

data

[object]

An array of team references for this schedule.

id [required]

string

The unique identifier of the team in this relationship.

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

type [required]

enum

Schedules resource type. Allowed enum values: schedules

default: schedules

included

[ <oneOf>]

Any additional resources related to this schedule, such as teams and layers.

Option 1

object

Provides a reference to a team, including ID, type, and basic attributes/relationships.

attributes

object

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.

relationships

object

Collects the key relationship fields for a team reference, specifically on-call users.

oncall_users

object

Defines which users are on-call within a team, stored as an array of references.

data

[object]

The list of user references who are on-call for this team.

id [required]

string

The unique identifier of the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

Option 2

object

Encapsulates a layer resource, holding attributes like rotation details, plus relationships to the members covering that layer.

attributes

object

Describes key properties of a Layer, including rotation details, name, start/end times, and any restrictions.

effective_date

date-time

When the layer becomes active (ISO 8601).

end_date

date-time

When the layer ceases to be active (ISO 8601).

interval

object

Defines how often the rotation repeats, using a combination of days and optional seconds.

days

int32

The number of days in each rotation cycle.

seconds

int64

Any additional seconds for the rotation cycle (up to 30 days).

name

string

The name of this layer.

restrictions

[object]

An optional list of time restrictions for when this layer is in effect.

end_day

enum

Defines the end day of the restriction within a Layer. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

end_time

string

The time of day the restriction ends (hh:mm:ss).

start_day

enum

Defines the start day of the restriction within a Layer. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

start_time

string

The time of day the restriction begins (hh:mm:ss).

rotation_start

date-time

The date/time when the rotation starts (ISO 8601).

id

string

A unique identifier for this layer.

relationships

object

Holds references to objects related to the Layer entity, such as its members.

members

object

Holds an array of references to the members of a Layer, each containing member IDs.

data

[object]

The list of members who belong to this layer.

id [required]

string

The unique user ID of the layer member.

type [required]

enum

Members resource type. Allowed enum values: members

default: members

type [required]

enum

Layers resource type. Allowed enum values: layers

default: layers

Option 3

object

Represents a single member entry in a schedule, referencing a specific user.

id

string

The unique identifier for this schedule member.

relationships

object

Defines relationships for a schedule member, primarily referencing a single user.

user

object

Wraps the user data reference for a schedule member.

data [required]

object

Points to the user data associated with this schedule member, including an ID and type.

id [required]

string

The user's unique identifier.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Schedule Members resource type. Allowed enum values: members

default: members

Option 4

object

Represents a user object in the context of a schedule, including their id, type, and basic attributes.

attributes

object

Provides basic user information for a schedule, including a name and email address.

email

string

The user's email address.

name

string

The user's name.

id

string

The unique user identifier.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

{
  "data": {
    "attributes": {
      "name": "Primary On-Call",
      "tags": [],
      "time_zone": "America/New_York"
    },
    "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
    "relationships": {
      "layers": {
        "data": [
          {
            "id": "00000000-0000-0000-0000-000000000001",
            "type": "layers"
          }
        ]
      },
      "teams": {
        "data": [
          {
            "id": "00000000-da3a-0000-0000-000000000000",
            "type": "teams"
          }
        ]
      }
    },
    "type": "schedules"
  },
  "included": []
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

"""
Get on-call schedule returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.on_call_api import OnCallApi

# there is a valid "schedule" in the system
SCHEDULE_DATA_ID = environ["SCHEDULE_DATA_ID"]

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = OnCallApi(api_client)
    response = api_instance.get_on_call_schedule(
        schedule_id=SCHEDULE_DATA_ID,
    )

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"

Delete on-call schedule

DELETE https://api.ap1.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.datadoghq.eu/api/v2/on-call/schedules/{schedule_id}https://api.ddog-gov.com/api/v2/on-call/schedules/{schedule_id}https://api.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.us3.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.us5.datadoghq.com/api/v2/on-call/schedules/{schedule_id}

Overview

Delete an on-call schedule

Arguments

Path Parameters

Name

Type

Description

schedule_id [required]

string

The ID of the schedule

Response

No Content

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

"""
Delete on-call schedule returns "No Content" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.on_call_api import OnCallApi

# there is a valid "schedule" in the system
SCHEDULE_DATA_ID = environ["SCHEDULE_DATA_ID"]

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = OnCallApi(api_client)
    api_instance.delete_on_call_schedule(
        schedule_id=SCHEDULE_DATA_ID,
    )

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"

Update on-call schedule

PUT https://api.ap1.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.datadoghq.eu/api/v2/on-call/schedules/{schedule_id}https://api.ddog-gov.com/api/v2/on-call/schedules/{schedule_id}https://api.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.us3.datadoghq.com/api/v2/on-call/schedules/{schedule_id}https://api.us5.datadoghq.com/api/v2/on-call/schedules/{schedule_id}

Overview

Update a new on-call schedule

Arguments

Path Parameters

Name

Type

Description

schedule_id [required]

string

The ID of the schedule

Query Strings

Name

Type

Description

include

string

Comma-separated list of included relationships to be returned. Allowed values: teams, layers, layers.members, layers.members.user.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Contains all data needed to update an existing schedule, including its attributes (such as name, layers, or tags) and any relationships to teams.

attributes [required]

object

Defines the updatable attributes for a schedule, such as name, time zone, tags, and layers.

layers [required]

[object]

The updated list of layers (rotations) for this schedule.

effective_date [required]

date-time

When this updated layer takes effect (ISO 8601 format).

end_date

date-time

When this updated layer should stop being active (ISO 8601 format).

id

string

A unique identifier for the layer being updated.

interval [required]

object

Specifies how the rotation repeats: number of days, plus optional seconds, up to the given maximums.

days

int32

How many days each rotation cycle should span.

seconds

int64

Additional seconds to add to the rotation cycle (for example, partial days).

members [required]

[object]

The members assigned to this layer.

user

object

Identifies the user who is assigned to this member object. Only id is required.

id

string

The user's ID.

name [required]

string

The name for this layer (for example, "Secondary Coverage").

restrictions

[object]

Any time restrictions that define when this layer is active.

end_day

enum

Defines the day of the week on which the time restriction ends. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

end_time

string

The time at which this restriction ends (hh:mm:ss).

start_day

enum

Defines the day of the week on which the time restriction starts. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

start_time

string

The time at which this restriction starts (hh:mm:ss).

rotation_start [required]

date-time

The date/time at which the rotation begins (ISO 8601 format).

name [required]

string

A short name for the schedule.

tags

[string]

A list of tags that you can associate with this schedule.

time_zone [required]

string

The time zone used when interpreting rotation times.

id [required]

string

The ID of the schedule to be updated.

relationships

object

Houses relationships for the schedule update, typically referencing teams.

teams

object

Defines the teams that this schedule update is associated with.

data

[object]

An array of team references.

id [required]

string

The unique team identifier.

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

type [required]

enum

Schedules resource type. Allowed enum values: schedules

default: schedules

{
  "data": {
    "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
    "attributes": {
      "layers": [
        {
          "id": "00000000-0000-0000-0000-000000000001",
          "effective_date": "2021-11-01T11:11:11+00:00",
          "end_date": "2021-11-21T11:11:11+00:00",
          "interval": {
            "seconds": 300
          },
          "members": [
            {
              "user": {
                "id": "string"
              }
            }
          ],
          "name": "Layer 1",
          "restrictions": [
            {
              "end_day": "friday",
              "end_time": "17:00:00",
              "start_day": "monday",
              "start_time": "09:00:00"
            }
          ],
          "rotation_start": "2021-11-06T11:11:11+00:00"
        }
      ],
      "name": "Example-On-Call",
      "tags": [
        "tag1",
        "tag2",
        "tag3"
      ],
      "time_zone": "America/New_York"
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "teams"
          }
        ]
      }
    },
    "type": "schedules"
  }
}

Response

OK

Top-level container for a schedule object, including both the data payload and any related included resources (such as teams, layers, or members).

Expand All

Field

Type

Description

data

object

Represents the primary data object for a schedule, linking attributes and relationships.

attributes

object

Provides core properties of a schedule object, such as its name, time zone, and tags.

name

string

A short name for the schedule.

tags

[string]

A list of tags associated with this schedule.

time_zone

string

The time zone in which this schedule operates.

id

string

The schedule's unique identifier.

relationships

object

Groups the relationships for a schedule object, referencing layers and teams.

layers

object

Associates layers with this schedule in a data structure.

data

[object]

An array of layer references for this schedule.

id [required]

string

The unique identifier of the layer in this relationship.

type [required]

enum

Layers resource type. Allowed enum values: layers

default: layers

teams

object

Associates teams with this schedule in a data structure.

data

[object]

An array of team references for this schedule.

id [required]

string

The unique identifier of the team in this relationship.

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

type [required]

enum

Schedules resource type. Allowed enum values: schedules

default: schedules

included

[ <oneOf>]

Any additional resources related to this schedule, such as teams and layers.

Option 1

object

Provides a reference to a team, including ID, type, and basic attributes/relationships.

attributes

object

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.

relationships

object

Collects the key relationship fields for a team reference, specifically on-call users.

oncall_users

object

Defines which users are on-call within a team, stored as an array of references.

data

[object]

The list of user references who are on-call for this team.

id [required]

string

The unique identifier of the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

Option 2

object

Encapsulates a layer resource, holding attributes like rotation details, plus relationships to the members covering that layer.

attributes

object

Describes key properties of a Layer, including rotation details, name, start/end times, and any restrictions.

effective_date

date-time

When the layer becomes active (ISO 8601).

end_date

date-time

When the layer ceases to be active (ISO 8601).

interval

object

Defines how often the rotation repeats, using a combination of days and optional seconds.

days

int32

The number of days in each rotation cycle.

seconds

int64

Any additional seconds for the rotation cycle (up to 30 days).

name

string

The name of this layer.

restrictions

[object]

An optional list of time restrictions for when this layer is in effect.

end_day

enum

Defines the end day of the restriction within a Layer. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

end_time

string

The time of day the restriction ends (hh:mm:ss).

start_day

enum

Defines the start day of the restriction within a Layer. Allowed enum values: monday,tuesday,wednesday,thursday,friday,saturday,sunday

start_time

string

The time of day the restriction begins (hh:mm:ss).

rotation_start

date-time

The date/time when the rotation starts (ISO 8601).

id

string

A unique identifier for this layer.

relationships

object

Holds references to objects related to the Layer entity, such as its members.

members

object

Holds an array of references to the members of a Layer, each containing member IDs.

data

[object]

The list of members who belong to this layer.

id [required]

string

The unique user ID of the layer member.

type [required]

enum

Members resource type. Allowed enum values: members

default: members

type [required]

enum

Layers resource type. Allowed enum values: layers

default: layers

Option 3

object

Represents a single member entry in a schedule, referencing a specific user.

id

string

The unique identifier for this schedule member.

relationships

object

Defines relationships for a schedule member, primarily referencing a single user.

user

object

Wraps the user data reference for a schedule member.

data [required]

object

Points to the user data associated with this schedule member, including an ID and type.

id [required]

string

The user's unique identifier.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Schedule Members resource type. Allowed enum values: members

default: members

Option 4

object

Represents a user object in the context of a schedule, including their id, type, and basic attributes.

attributes

object

Provides basic user information for a schedule, including a name and email address.

email

string

The user's email address.

name

string

The user's name.

id

string

The unique user identifier.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

{
  "data": {
    "attributes": {
      "name": "Primary On-Call",
      "tags": [],
      "time_zone": "America/New_York"
    },
    "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
    "relationships": {
      "layers": {
        "data": [
          {
            "id": "00000000-0000-0000-0000-000000000001",
            "type": "layers"
          }
        ]
      },
      "teams": {
        "data": [
          {
            "id": "00000000-da3a-0000-0000-000000000000",
            "type": "teams"
          }
        ]
      }
    },
    "type": "schedules"
  },
  "included": []
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

"""
Update on-call schedule returns "OK" response
"""

from datetime import datetime
from dateutil.relativedelta import relativedelta
from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.on_call_api import OnCallApi
from datadog_api_client.v2.model.schedule_update_request import ScheduleUpdateRequest
from datadog_api_client.v2.model.schedule_update_request_data import ScheduleUpdateRequestData
from datadog_api_client.v2.model.schedule_update_request_data_attributes import ScheduleUpdateRequestDataAttributes
from datadog_api_client.v2.model.schedule_update_request_data_attributes_layers_items import (
    ScheduleUpdateRequestDataAttributesLayersItems,
)
from datadog_api_client.v2.model.schedule_update_request_data_attributes_layers_items_interval import (
    ScheduleUpdateRequestDataAttributesLayersItemsInterval,
)
from datadog_api_client.v2.model.schedule_update_request_data_attributes_layers_items_members_items import (
    ScheduleUpdateRequestDataAttributesLayersItemsMembersItems,
)
from datadog_api_client.v2.model.schedule_update_request_data_attributes_layers_items_members_items_user import (
    ScheduleUpdateRequestDataAttributesLayersItemsMembersItemsUser,
)
from datadog_api_client.v2.model.schedule_update_request_data_attributes_layers_items_restrictions_items import (
    ScheduleUpdateRequestDataAttributesLayersItemsRestrictionsItems,
)
from datadog_api_client.v2.model.schedule_update_request_data_attributes_layers_items_restrictions_items_end_day import (
    ScheduleUpdateRequestDataAttributesLayersItemsRestrictionsItemsEndDay,
)
from datadog_api_client.v2.model.schedule_update_request_data_attributes_layers_items_restrictions_items_start_day import (
    ScheduleUpdateRequestDataAttributesLayersItemsRestrictionsItemsStartDay,
)
from datadog_api_client.v2.model.schedule_update_request_data_relationships import (
    ScheduleUpdateRequestDataRelationships,
)
from datadog_api_client.v2.model.schedule_update_request_data_relationships_teams import (
    ScheduleUpdateRequestDataRelationshipsTeams,
)
from datadog_api_client.v2.model.schedule_update_request_data_relationships_teams_data_items import (
    ScheduleUpdateRequestDataRelationshipsTeamsDataItems,
)
from datadog_api_client.v2.model.schedule_update_request_data_relationships_teams_data_items_type import (
    ScheduleUpdateRequestDataRelationshipsTeamsDataItemsType,
)
from datadog_api_client.v2.model.schedule_update_request_data_type import ScheduleUpdateRequestDataType

# there is a valid "schedule" in the system
SCHEDULE_DATA_ID = environ["SCHEDULE_DATA_ID"]
SCHEDULE_DATA_RELATIONSHIPS_LAYERS_DATA_0_ID = environ["SCHEDULE_DATA_RELATIONSHIPS_LAYERS_DATA_0_ID"]

# there is a valid "user" in the system
USER_DATA_ID = environ["USER_DATA_ID"]

# there is a valid "team" in the system
TEAM_DATA_ID = environ["TEAM_DATA_ID"]

body = ScheduleUpdateRequest(
    data=ScheduleUpdateRequestData(
        id=SCHEDULE_DATA_ID,
        attributes=ScheduleUpdateRequestDataAttributes(
            layers=[
                ScheduleUpdateRequestDataAttributesLayersItems(
                    id=SCHEDULE_DATA_RELATIONSHIPS_LAYERS_DATA_0_ID,
                    effective_date=(datetime.now() + relativedelta(days=-10)),
                    end_date=(datetime.now() + relativedelta(days=10)),
                    interval=ScheduleUpdateRequestDataAttributesLayersItemsInterval(
                        seconds=300,
                    ),
                    members=[
                        ScheduleUpdateRequestDataAttributesLayersItemsMembersItems(
                            user=ScheduleUpdateRequestDataAttributesLayersItemsMembersItemsUser(
                                id=USER_DATA_ID,
                            ),
                        ),
                    ],
                    name="Layer 1",
                    restrictions=[
                        ScheduleUpdateRequestDataAttributesLayersItemsRestrictionsItems(
                            end_day=ScheduleUpdateRequestDataAttributesLayersItemsRestrictionsItemsEndDay.FRIDAY,
                            end_time="17:00:00",
                            start_day=ScheduleUpdateRequestDataAttributesLayersItemsRestrictionsItemsStartDay.MONDAY,
                            start_time="09:00:00",
                        ),
                    ],
                    rotation_start=(datetime.now() + relativedelta(days=-5)),
                ),
            ],
            name="Example-On-Call",
            tags=[
                "tag1",
                "tag2",
                "tag3",
            ],
            time_zone="America/New_York",
        ),
        relationships=ScheduleUpdateRequestDataRelationships(
            teams=ScheduleUpdateRequestDataRelationshipsTeams(
                data=[
                    ScheduleUpdateRequestDataRelationshipsTeamsDataItems(
                        id=TEAM_DATA_ID,
                        type=ScheduleUpdateRequestDataRelationshipsTeamsDataItemsType.TEAMS,
                    ),
                ],
            ),
        ),
        type=ScheduleUpdateRequestDataType.SCHEDULES,
    ),
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = OnCallApi(api_client)
    response = api_instance.update_on_call_schedule(schedule_id=SCHEDULE_DATA_ID, body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"

Create on call escalation policy

POST https://api.ap1.datadoghq.com/api/v2/on-call/escalation-policieshttps://api.datadoghq.eu/api/v2/on-call/escalation-policieshttps://api.ddog-gov.com/api/v2/on-call/escalation-policieshttps://api.datadoghq.com/api/v2/on-call/escalation-policieshttps://api.us3.datadoghq.com/api/v2/on-call/escalation-policieshttps://api.us5.datadoghq.com/api/v2/on-call/escalation-policies

Overview

Create a new on-call escalation policy

Arguments

Query Strings

Name

Type

Description

include

string

Comma-separated list of included relationships to be returned. Allowed values: teams, steps, steps.targets.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Represents the data for creating an escalation policy, including its attributes, relationships, and resource type.

attributes [required]

object

Defines the attributes for creating an escalation policy, including its description, name, resolution behavior, retries, and steps.

description

string

Provides a detailed text description of the new escalation policy.

name [required]

string

Specifies the name for the new escalation policy.

resolve_page_on_policy_end

boolean

Indicates whether the page is automatically resolved when the policy ends.

retries

int64

Specifies how many times the escalation sequence is retried if there is no response.

steps [required]

[object]

A list of escalation steps, each defining assignment, escalation timeout, and targets for the new policy.

assignment

enum

Specifies how this escalation step will assign targets (example default or round-robin). Allowed enum values: default,round-robin

escalate_after_seconds

int64

Defines how many seconds to wait before escalating to the next step.

targets [required]

[object]

Specifies the collection of escalation targets for this step.

id

string

Specifies the unique identifier for this target.

type

enum

Specifies the type of escalation target (example users, schedules, or teams). Allowed enum values: users,schedules,teams

relationships

object

Represents relationships in an escalation policy creation request, including references to teams.

teams

object

Defines the relationship to teams within an escalation policy creation request, referencing the teams to be associated with the policy.

data

[object]

An array of team references for the new escalation policy.

id [required]

string

Specifies the unique identifier for the related team.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

type [required]

enum

Indicates that the resource is of type policies. Allowed enum values: policies

default: policies

{
  "data": {
    "attributes": {
      "description": "Escalation Policy 1 description",
      "name": "Example-On-Call",
      "resolve_page_on_policy_end": true,
      "retries": 2,
      "steps": [
        {
          "assignment": "default",
          "escalate_after_seconds": 3600,
          "targets": [
            {
              "id": "string",
              "type": "users"
            },
            {
              "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
              "type": "schedules"
            },
            {
              "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
              "type": "teams"
            }
          ]
        },
        {
          "assignment": "round-robin",
          "escalate_after_seconds": 3600,
          "targets": [
            {
              "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
              "type": "teams"
            }
          ]
        }
      ]
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "teams"
          }
        ]
      }
    },
    "type": "policies"
  }
}

Response

Created

Represents a complete escalation policy response, including policy data and optionally included related resources.

Expand All

Field

Type

Description

data

object

Represents the data for a single escalation policy, including its attributes, ID, relationships, and resource type.

attributes

object

Defines the main attributes of an escalation policy, such as its description, name, and behavior on policy end.

description

string

Provides a detailed text description of the escalation policy.

name [required]

string

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

int64

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

object

Represents the relationships for an escalation policy, including references to steps and teams.

steps [required]

object

Defines the relationship to a collection of steps within an escalation policy. Contains an array of step data references.

data

[object]

An array of references to the steps defined in this escalation policy.

id [required]

string

Specifies the unique identifier for the step resource.

type [required]

enum

Indicates that the resource is of type steps. Allowed enum values: steps

default: steps

teams

object

Defines the relationship to a collection of teams within an escalation policy. Contains an array of team data references.

data

[object]

An array of references to the teams associated with this escalation policy.

id [required]

string

Specifies the unique identifier for the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

type [required]

enum

Indicates that the resource is of type policies. Allowed enum values: policies

default: policies

included

[ <oneOf>]

Provides any included related resources, such as steps or targets, returned with the policy.

Option 1

object

Provides a reference to a team, including ID, type, and basic attributes/relationships.

attributes

object

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.

relationships

object

Collects the key relationship fields for a team reference, specifically on-call users.

oncall_users

object

Defines which users are on-call within a team, stored as an array of references.

data

[object]

The list of user references who are on-call for this team.

id [required]

string

The unique identifier of the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

Option 2

object

Represents a single step in an escalation policy, including its attributes, relationships, and resource type.

attributes

object

Defines attributes for an escalation policy step, such as assignment strategy and escalation timeout.

assignment

enum

Specifies how this escalation step will assign targets (example default or round-robin). Allowed enum values: default,round-robin

escalate_after_seconds

int64

Specifies how many seconds to wait before escalating to the next step.

id

string

Specifies the unique identifier of this escalation policy step.

relationships

object

Represents the relationship of an escalation policy step to its targets.

targets

 <oneOf>

Represents an escalation target, which can be a team, user, or schedule.

Option 1

object

Represents a team target for an escalation policy step, including the team's ID and resource type.

id [required]

string

Specifies the unique identifier of the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

Option 2

object

Represents a user target for an escalation policy step, including the user's ID and resource type.

id [required]

string

Specifies the unique identifier of the user resource.

type [required]

enum

Indicates that the resource is of type users. Allowed enum values: users

default: users

Option 3

object

Represents a schedule target for an escalation policy step, including its ID and resource type.

id [required]

string

Specifies the unique identifier of the schedule resource.

type [required]

enum

Indicates that the resource is of type schedules. Allowed enum values: schedules

default: schedules

type [required]

enum

Indicates that the resource is of type steps. Allowed enum values: steps

default: steps

Option 3

object

Represents a user target for an escalation policy step, including the user's ID and resource type.

id [required]

string

Specifies the unique identifier of the user resource.

type [required]

enum

Indicates that the resource is of type users. Allowed enum values: users

default: users

Option 4

object

Represents a schedule target for an escalation policy step, including its ID and resource type.

id [required]

string

Specifies the unique identifier of the schedule resource.

type [required]

enum

Indicates that the resource is of type schedules. Allowed enum values: schedules

default: schedules

Option 5

object

Represents a team target for an escalation policy step, including the team's ID and resource type.

id [required]

string

Specifies the unique identifier of the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

{
  "data": {
    "attributes": {
      "description": "string",
      "name": "On-call Escalation Policy",
      "resolve_page_on_policy_end": false,
      "retries": "integer"
    },
    "id": "string",
    "relationships": {
      "steps": {
        "data": [
          {
            "id": "00000000-aba1-0000-0000-000000000000",
            "type": "steps"
          }
        ]
      },
      "teams": {
        "data": [
          {
            "id": "00000000-aba1-0000-0000-000000000000",
            "type": "teams"
          }
        ]
      }
    },
    "type": "policies"
  },
  "included": []
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          # Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/on-call/escalation-policies" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "description": "Escalation Policy 1 description",
      "name": "Example-On-Call",
      "resolve_page_on_policy_end": true,
      "retries": 2,
      "steps": [
        {
          "assignment": "default",
          "escalate_after_seconds": 3600,
          "targets": [
            {
              "id": "string",
              "type": "users"
            },
            {
              "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
              "type": "schedules"
            },
            {
              "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
              "type": "teams"
            }
          ]
        },
        {
          "assignment": "round-robin",
          "escalate_after_seconds": 3600,
          "targets": [
            {
              "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
              "type": "teams"
            }
          ]
        }
      ]
    },
    "relationships": {
      "teams": {
        "data": [
          {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "teams"
          }
        ]
      }
    },
    "type": "policies"
  }
}
EOF

Update on call escalation policy

PUT https://api.ap1.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.datadoghq.eu/api/v2/on-call/escalation-policies/{policy_id}https://api.ddog-gov.com/api/v2/on-call/escalation-policies/{policy_id}https://api.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.us3.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.us5.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}

Overview

Update an on-call escalation policy

Arguments

Path Parameters

Name

Type

Description

policy_id [required]

string

The ID of the escalation policy

Query Strings

Name

Type

Description

include

string

Comma-separated list of included relationships to be returned. Allowed values: teams, steps, steps.targets.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Represents the data for updating an existing escalation policy, including its ID, attributes, relationships, and resource type.

attributes [required]

object

Defines the attributes that can be updated for an escalation policy, such as description, name, resolution behavior, retries, and steps.

description

string

Provides a detailed text description of the escalation policy.

name [required]

string

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

int64

Specifies how many times the escalation sequence is retried if there is no response.

steps [required]

[object]

A list of escalation steps, each defining assignment, escalation timeout, and targets.

assignment

enum

Specifies how this escalation step will assign targets (example default or round-robin). Allowed enum values: default,round-robin

escalate_after_seconds

int64

Defines how many seconds to wait before escalating to the next step.

id

string

Specifies the unique identifier of this step.

targets [required]

[object]

Specifies the collection of escalation targets for this step.

id

string

Specifies the unique identifier for this target.

type

enum

Specifies the type of escalation target (example users, schedules, or teams). Allowed enum values: users,schedules,teams

id [required]

string

Specifies the unique identifier of the escalation policy being updated.

relationships

object

Represents relationships in an escalation policy update request, including references to teams.

teams

object

Defines the relationship to teams within an escalation policy update request, referencing the teams to be associated with or removed from the policy.

data

[object]

An array of team references for the escalation policy update.

id [required]

string

Specifies the unique identifier for the related team.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

type [required]

enum

Indicates that the resource is of type policies. Allowed enum values: policies

default: policies

{
  "data": {
    "attributes": {
      "description": "Example-On-Call",
      "name": "Example-On-Call-updated",
      "resolve_page_on_policy_end": false,
      "retries": 0,
      "steps": [
        {
          "assignment": "default",
          "escalate_after_seconds": 3600,
          "id": "00000000-aba1-0000-0000-000000000000",
          "targets": [
            {
              "id": "c1d4eb9e-8bb0-974d-85a5-a7dd9db46bee",
              "type": "users"
            }
          ]
        }
      ]
    },
    "id": "string",
    "relationships": {
      "teams": {
        "data": [
          {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "teams"
          }
        ]
      }
    },
    "type": "policies"
  }
}

Response

OK

Represents a complete escalation policy response, including policy data and optionally included related resources.

Expand All

Field

Type

Description

data

object

Represents the data for a single escalation policy, including its attributes, ID, relationships, and resource type.

attributes

object

Defines the main attributes of an escalation policy, such as its description, name, and behavior on policy end.

description

string

Provides a detailed text description of the escalation policy.

name [required]

string

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

int64

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

object

Represents the relationships for an escalation policy, including references to steps and teams.

steps [required]

object

Defines the relationship to a collection of steps within an escalation policy. Contains an array of step data references.

data

[object]

An array of references to the steps defined in this escalation policy.

id [required]

string

Specifies the unique identifier for the step resource.

type [required]

enum

Indicates that the resource is of type steps. Allowed enum values: steps

default: steps

teams

object

Defines the relationship to a collection of teams within an escalation policy. Contains an array of team data references.

data

[object]

An array of references to the teams associated with this escalation policy.

id [required]

string

Specifies the unique identifier for the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

type [required]

enum

Indicates that the resource is of type policies. Allowed enum values: policies

default: policies

included

[ <oneOf>]

Provides any included related resources, such as steps or targets, returned with the policy.

Option 1

object

Provides a reference to a team, including ID, type, and basic attributes/relationships.

attributes

object

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.

relationships

object

Collects the key relationship fields for a team reference, specifically on-call users.

oncall_users

object

Defines which users are on-call within a team, stored as an array of references.

data

[object]

The list of user references who are on-call for this team.

id [required]

string

The unique identifier of the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

Option 2

object

Represents a single step in an escalation policy, including its attributes, relationships, and resource type.

attributes

object

Defines attributes for an escalation policy step, such as assignment strategy and escalation timeout.

assignment

enum

Specifies how this escalation step will assign targets (example default or round-robin). Allowed enum values: default,round-robin

escalate_after_seconds

int64

Specifies how many seconds to wait before escalating to the next step.

id

string

Specifies the unique identifier of this escalation policy step.

relationships

object

Represents the relationship of an escalation policy step to its targets.

targets

 <oneOf>

Represents an escalation target, which can be a team, user, or schedule.

Option 1

object

Represents a team target for an escalation policy step, including the team's ID and resource type.

id [required]

string

Specifies the unique identifier of the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

Option 2

object

Represents a user target for an escalation policy step, including the user's ID and resource type.

id [required]

string

Specifies the unique identifier of the user resource.

type [required]

enum

Indicates that the resource is of type users. Allowed enum values: users

default: users

Option 3

object

Represents a schedule target for an escalation policy step, including its ID and resource type.

id [required]

string

Specifies the unique identifier of the schedule resource.

type [required]

enum

Indicates that the resource is of type schedules. Allowed enum values: schedules

default: schedules

type [required]

enum

Indicates that the resource is of type steps. Allowed enum values: steps

default: steps

Option 3

object

Represents a user target for an escalation policy step, including the user's ID and resource type.

id [required]

string

Specifies the unique identifier of the user resource.

type [required]

enum

Indicates that the resource is of type users. Allowed enum values: users

default: users

Option 4

object

Represents a schedule target for an escalation policy step, including its ID and resource type.

id [required]

string

Specifies the unique identifier of the schedule resource.

type [required]

enum

Indicates that the resource is of type schedules. Allowed enum values: schedules

default: schedules

Option 5

object

Represents a team target for an escalation policy step, including the team's ID and resource type.

id [required]

string

Specifies the unique identifier of the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

{
  "data": {
    "attributes": {
      "description": "string",
      "name": "On-call Escalation Policy",
      "resolve_page_on_policy_end": false,
      "retries": "integer"
    },
    "id": "string",
    "relationships": {
      "steps": {
        "data": [
          {
            "id": "00000000-aba1-0000-0000-000000000000",
            "type": "steps"
          }
        ]
      },
      "teams": {
        "data": [
          {
            "id": "00000000-aba1-0000-0000-000000000000",
            "type": "teams"
          }
        ]
      }
    },
    "type": "policies"
  },
  "included": []
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          # Path parameters
export policy_id="a3000000-0000-0000-0000-000000000000"
# Curl command
curl -X PUT "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/on-call/escalation-policies/${policy_id}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "description": "Example-On-Call",
      "name": "Example-On-Call-updated",
      "resolve_page_on_policy_end": false,
      "retries": 0,
      "steps": [
        {
          "assignment": "default",
          "escalate_after_seconds": 3600,
          "id": "00000000-aba1-0000-0000-000000000000",
          "targets": [
            {
              "id": "c1d4eb9e-8bb0-974d-85a5-a7dd9db46bee",
              "type": "users"
            }
          ]
        }
      ]
    },
    "id": "string",
    "relationships": {
      "teams": {
        "data": [
          {
            "id": "aeadc05e-98a8-11ec-ac2c-da7ad0900001",
            "type": "teams"
          }
        ]
      }
    },
    "type": "policies"
  }
}
EOF

Get on call escalation policy

GET https://api.ap1.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.datadoghq.eu/api/v2/on-call/escalation-policies/{policy_id}https://api.ddog-gov.com/api/v2/on-call/escalation-policies/{policy_id}https://api.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.us3.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.us5.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}

Overview

Get an on-call escalation policy

Arguments

Path Parameters

Name

Type

Description

policy_id [required]

string

The ID of the escalation policy

Query Strings

Name

Type

Description

include

string

Comma-separated list of included relationships to be returned. Allowed values: teams, steps, steps.targets.

Response

OK

Represents a complete escalation policy response, including policy data and optionally included related resources.

Expand All

Field

Type

Description

data

object

Represents the data for a single escalation policy, including its attributes, ID, relationships, and resource type.

attributes

object

Defines the main attributes of an escalation policy, such as its description, name, and behavior on policy end.

description

string

Provides a detailed text description of the escalation policy.

name [required]

string

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

int64

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

object

Represents the relationships for an escalation policy, including references to steps and teams.

steps [required]

object

Defines the relationship to a collection of steps within an escalation policy. Contains an array of step data references.

data

[object]

An array of references to the steps defined in this escalation policy.

id [required]

string

Specifies the unique identifier for the step resource.

type [required]

enum

Indicates that the resource is of type steps. Allowed enum values: steps

default: steps

teams

object

Defines the relationship to a collection of teams within an escalation policy. Contains an array of team data references.

data

[object]

An array of references to the teams associated with this escalation policy.

id [required]

string

Specifies the unique identifier for the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

type [required]

enum

Indicates that the resource is of type policies. Allowed enum values: policies

default: policies

included

[ <oneOf>]

Provides any included related resources, such as steps or targets, returned with the policy.

Option 1

object

Provides a reference to a team, including ID, type, and basic attributes/relationships.

attributes

object

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.

relationships

object

Collects the key relationship fields for a team reference, specifically on-call users.

oncall_users

object

Defines which users are on-call within a team, stored as an array of references.

data

[object]

The list of user references who are on-call for this team.

id [required]

string

The unique identifier of the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

Option 2

object

Represents a single step in an escalation policy, including its attributes, relationships, and resource type.

attributes

object

Defines attributes for an escalation policy step, such as assignment strategy and escalation timeout.

assignment

enum

Specifies how this escalation step will assign targets (example default or round-robin). Allowed enum values: default,round-robin

escalate_after_seconds

int64

Specifies how many seconds to wait before escalating to the next step.

id

string

Specifies the unique identifier of this escalation policy step.

relationships

object

Represents the relationship of an escalation policy step to its targets.

targets

 <oneOf>

Represents an escalation target, which can be a team, user, or schedule.

Option 1

object

Represents a team target for an escalation policy step, including the team's ID and resource type.

id [required]

string

Specifies the unique identifier of the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

Option 2

object

Represents a user target for an escalation policy step, including the user's ID and resource type.

id [required]

string

Specifies the unique identifier of the user resource.

type [required]

enum

Indicates that the resource is of type users. Allowed enum values: users

default: users

Option 3

object

Represents a schedule target for an escalation policy step, including its ID and resource type.

id [required]

string

Specifies the unique identifier of the schedule resource.

type [required]

enum

Indicates that the resource is of type schedules. Allowed enum values: schedules

default: schedules

type [required]

enum

Indicates that the resource is of type steps. Allowed enum values: steps

default: steps

Option 3

object

Represents a user target for an escalation policy step, including the user's ID and resource type.

id [required]

string

Specifies the unique identifier of the user resource.

type [required]

enum

Indicates that the resource is of type users. Allowed enum values: users

default: users

Option 4

object

Represents a schedule target for an escalation policy step, including its ID and resource type.

id [required]

string

Specifies the unique identifier of the schedule resource.

type [required]

enum

Indicates that the resource is of type schedules. Allowed enum values: schedules

default: schedules

Option 5

object

Represents a team target for an escalation policy step, including the team's ID and resource type.

id [required]

string

Specifies the unique identifier of the team resource.

type [required]

enum

Indicates that the resource is of type teams. Allowed enum values: teams

default: teams

{
  "data": {
    "attributes": {
      "description": "string",
      "name": "On-call Escalation Policy",
      "resolve_page_on_policy_end": false,
      "retries": "integer"
    },
    "id": "string",
    "relationships": {
      "steps": {
        "data": [
          {
            "id": "00000000-aba1-0000-0000-000000000000",
            "type": "steps"
          }
        ]
      },
      "teams": {
        "data": [
          {
            "id": "00000000-aba1-0000-0000-000000000000",
            "type": "teams"
          }
        ]
      }
    },
    "type": "policies"
  },
  "included": []
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export policy_id="a3000000-0000-0000-0000-000000000000"
# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/on-call/escalation-policies/${policy_id}" \
-H "Accept: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

Delete on call escalation policy

DELETE https://api.ap1.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.datadoghq.eu/api/v2/on-call/escalation-policies/{policy_id}https://api.ddog-gov.com/api/v2/on-call/escalation-policies/{policy_id}https://api.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.us3.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}https://api.us5.datadoghq.com/api/v2/on-call/escalation-policies/{policy_id}

Overview

Delete an on-call escalation policy

Arguments

Path Parameters

Name

Type

Description

policy_id [required]

string

The ID of the escalation policy

Response

No Content

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export policy_id="a3000000-0000-0000-0000-000000000000"
# Curl command
curl -X DELETE "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/on-call/escalation-policies/${policy_id}" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
PREVIEWING: cswatt/aws-api-gateway