Downtimes

Downtiming gives you greater control over monitor notifications by allowing you to globally exclude scopes from alerting. Downtime settings, which can be scheduled with start and end times, prevent all alerting related to specified Datadog tags.

Cancel a downtime

delete https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/{downtime_id}

Overview

Cancel a downtime.

Arguments

Path Parameters

Name

Type

Description

downtime_id [required]

integer

ID of the downtime to cancel.

Response

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Downtime not found

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Code Example

curl

                                        # Path parameters
export downtime_id="123456"
# Curl command
curl -X delete https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/${downtime_id} \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"

                                        

Cancel downtimes by scope

post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/cancel/by_scope

Overview

Delete all downtimes that match the scope of X.

Request

Body Data (required)

Scope to cancel downtimes for.

Expand All

Field

Type

Description

scope [required]

string

The scope(s) to which the downtime applies. For example, host:app2. Provide multiple scopes as a comma-separated list like env:dev,env:prod. The resulting downtime applies to sources that matches ALL provided scopes (env:dev AND env:prod).

{
  "scope": "host:myserver"
}

Response

Object containing array of IDs of canceled downtimes.

Expand All

Field

Type

Description

cancelled_ids

[integer]

ID of downtimes that were canceled.

{
  "cancelled_ids": [
    "123456789",
    "123456790"
  ]
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Downtimes not found

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Code Example

curl
python
ruby

                                        # Curl command
curl -X post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/cancel/by_scope \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}" \
-d @- << EOF
{
  "scope": "host:myserver"
}
EOF

                                        
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

# Cancel all downtimes with scope
api.Downtime.cancel_downtime_by_scope('env:testing')
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

# Cancel all downtimes with the given scope
dog.cancel_downtime_by_scope('env:testing')

Get a downtime

get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/{downtime_id}

Overview

Get downtime detail by downtime_id.

Arguments

Path Parameters

Name

Type

Description

downtime_id [required]

integer

ID of the downtime to fetch.

Response

Expand All

Field

Type

Description

active

boolean

If a scheduled downtime currently exists.

canceled

int64

If a scheduled downtime is canceled.

creator_id

int32

User ID of the downtime creator.

disabled

boolean

If a downtime has been disabled.

downtime_type

int32

0 for a downtime applied on * or all, 1 when the downtime is only scoped to hosts, or 2 when the downtime is scoped to anything but hosts.

end

int64

POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely until you cancel it.

int64

The downtime ID.

message

string

A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same @username notation as events.

monitor_id

int64

A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.

monitor_tags

[string]

A comma-separated list of monitor tags. For example, tags that are applied directly to monitors, not tags that are used in monitor queries (which are filtered by the scope parameter), to which the downtime applies. The resulting downtime applies to monitors that match ALL provided monitor tags. For example, service:postgres AND team:frontend.

parent_id

int64

ID of the parent Downtime.

recurrence

object

An object defining the recurrence of the downtime.

scope

[string]

start

int64

POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.

timezone

string

The timezone for the downtime.

updater_id

int32

ID of the last user that updated the downtime.

{
  "active": true,
  "canceled": "1412799983",
  "creator_id": "123456",
  "disabled": false,
  "downtime_type": "2",
  "end": "1412793983",
  "id": "1625",
  "message": "Message on the downtime",
  "monitor_id": "123456",
  "monitor_tags": [
    "*"
  ],
  "parent_id": "123",
  "recurrence": {
    "period": "1",
    "type": "weeks",
    "until_date": "1447786293",
    "until_occurrences": "2",
    "week_days": [
      "Mon",
      "Tue"
    ]
  },
  "scope": [
    "env:staging"
  ],
  "start": "1412792983",
  "timezone": "America/New_York",
  "updater_id": "123456"
}

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Downtime not found

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Code Example

curl
python
ruby

                                        # Path parameters
export downtime_id="123456"
# Curl command
curl -X get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/${downtime_id} \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"

                                        
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

# Get a downtime
api.Downtime.get(2910)
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

# Get a downtime object
downtime_id = 1625
dog.get_downtime(downtime_id)

Get all downtimes

get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime

Overview

Get all scheduled downtimes.

Arguments

Query Strings

Name

Type

Description

current_only

boolean

Only return downtimes that are active when the request is made.

Response

Expand All

Field

Type

Description

active

boolean

If a scheduled downtime currently exists.

canceled

int64

If a scheduled downtime is canceled.

creator_id

int32

User ID of the downtime creator.

disabled

boolean

If a downtime has been disabled.

downtime_type

int32

0 for a downtime applied on * or all, 1 when the downtime is only scoped to hosts, or 2 when the downtime is scoped to anything but hosts.

end

int64

POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely until you cancel it.

int64

The downtime ID.

message

string

A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same @username notation as events.

monitor_id

int64

A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.

monitor_tags

[string]

parent_id

int64

ID of the parent Downtime.

recurrence

object

An object defining the recurrence of the downtime.

scope

[string]

start

int64

POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.

timezone

string

The timezone for the downtime.

updater_id

int32

ID of the last user that updated the downtime.

{
  "active": true,
  "canceled": "1412799983",
  "creator_id": "123456",
  "disabled": false,
  "downtime_type": "2",
  "end": "1412793983",
  "id": "1625",
  "message": "Message on the downtime",
  "monitor_id": "123456",
  "monitor_tags": [
    "*"
  ],
  "parent_id": "123",
  "recurrence": {
    "period": "1",
    "type": "weeks",
    "until_date": "1447786293",
    "until_occurrences": "2",
    "week_days": [
      "Mon",
      "Tue"
    ]
  },
  "scope": [
    "env:staging"
  ],
  "start": "1412792983",
  "timezone": "America/New_York",
  "updater_id": "123456"
}

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Code Example

curl
python
ruby

                                        # Curl command
curl -X get https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}"

                                        
from datadog import initialize, api

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

# Get all downtimes
print(api.Downtime.get_all())
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

# Get all downtimes
dog.get_all_downtimes

Schedule a downtime

post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime

Overview

Schedule a downtime.

Request

Body Data (required)

Schedule a downtime request body.

Expand All

Field

Type

Description

active

boolean

If a scheduled downtime currently exists.

canceled

int64

If a scheduled downtime is canceled.

creator_id

int32

User ID of the downtime creator.

disabled

boolean

If a downtime has been disabled.

downtime_type

int32

0 for a downtime applied on * or all, 1 when the downtime is only scoped to hosts, or 2 when the downtime is scoped to anything but hosts.

end

int64

POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely until you cancel it.

int64

The downtime ID.

message

string

A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same @username notation as events.

monitor_id

int64

A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.

monitor_tags

[string]

parent_id

int64

ID of the parent Downtime.

recurrence

object

An object defining the recurrence of the downtime.

scope

[string]

start

int64

POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.

timezone

string

The timezone for the downtime.

updater_id

int32

ID of the last user that updated the downtime.

{
  "disabled": false,
  "end": "1412793983",
  "message": "Message on the downtime",
  "monitor_id": "123456",
  "monitor_tags": [
    "*"
  ],
  "parent_id": "123",
  "recurrence": {
    "period": "1",
    "type": "weeks",
    "until_date": "1447786293",
    "until_occurrences": "2",
    "week_days": [
      "Mon",
      "Tue"
    ]
  },
  "scope": [
    "env:staging"
  ],
  "start": "1412792983",
  "timezone": "America/New_York"
}

Response

Expand All

Field

Type

Description

active

boolean

If a scheduled downtime currently exists.

canceled

int64

If a scheduled downtime is canceled.

creator_id

int32

User ID of the downtime creator.

disabled

boolean

If a downtime has been disabled.

downtime_type

int32

0 for a downtime applied on * or all, 1 when the downtime is only scoped to hosts, or 2 when the downtime is scoped to anything but hosts.

end

int64

POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely until you cancel it.

int64

The downtime ID.

message

string

A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same @username notation as events.

monitor_id

int64

A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.

monitor_tags

[string]

parent_id

int64

ID of the parent Downtime.

recurrence

object

An object defining the recurrence of the downtime.

scope

[string]

start

int64

POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.

timezone

string

The timezone for the downtime.

updater_id

int32

ID of the last user that updated the downtime.

{
  "active": true,
  "canceled": "1412799983",
  "creator_id": "123456",
  "disabled": false,
  "downtime_type": "2",
  "end": "1412793983",
  "id": "1625",
  "message": "Message on the downtime",
  "monitor_id": "123456",
  "monitor_tags": [
    "*"
  ],
  "parent_id": "123",
  "recurrence": {
    "period": "1",
    "type": "weeks",
    "until_date": "1447786293",
    "until_occurrences": "2",
    "week_days": [
      "Mon",
      "Tue"
    ]
  },
  "scope": [
    "env:staging"
  ],
  "start": "1412792983",
  "timezone": "America/New_York",
  "updater_id": "123456"
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Code Example

curl
python
ruby

                                        # Curl command
curl -X post https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}" \
-d @- << EOF
{}
EOF

                                        
from datadog import initialize, api
import time

options = {
    'api_key': '<DATADOG_API_KEY>',
    'app_key': '<DATADOG_APPLICATION_KEY>'
}

initialize(**options)

# Repeat for 3 hours (starting now) on every week day for 4 weeks.
start_ts = int(time.time())
end_ts = start_ts + (3 * 60 * 60)
end_reccurrence_ts = start_ts + (4 * 7 * 24 * 60 * 60)  # 4 weeks from now

recurrence = {
    'type': 'weeks',
    'period': 1,
    'week_days': ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
    'until_date': end_reccurrence_ts
}

# Schedule downtime
api.Downtime.create(
    scope='env:staging',
    start=start_ts,
    end=end_ts,
    recurrence=recurrence
)

# OR use RRULE reccurence
rrule_recurrence = {
    'type': 'rrule',
    'rrule': 'FREQ=MONTHLY;BYSETPOS=3;BYDAY=WE;INTERVAL=1',
}

# Schedule downtime
api.Downtime.create(
    scope='env:staging',
    start=start_ts,
    end=end_ts,
    recurrence=rrule_recurrence
)
require 'dogapi'

api_key = '<DATADOG_API_KEY>'
app_key = '<DATADOG_APPLICATION_KEY>'

dog = Dogapi::Client.new(api_key, app_key)

# Repeat for 3 hours (starting now) on every week day for 4 weeks.
start_ts = Time.now.to_i
end_ts = start_ts + (3 * 60 * 60)
end_reccurrence_ts = start_ts + (4 * 7 * 24 * 60 * 60) # 4 weeks from now

recurrence = {
    'type' => 'weeks',
    'period' => 1,
    'week_days' => %w[Mon Tue Wed Thu Fri],
    'until_date' => end_reccurrence_ts
}

# Schedule downtime
dog.Downtime.create(
    'env:staging',
    start: start_ts,
    end: end_ts,
    recurrence: recurrence
)

# OR use RRULE reccurence
rrule_recurrence = {
    'type' => 'rrule',
    'rrule' => 'FREQ=MONTHLY;BYSETPOS=3;BYDAY=WE;INTERVAL=1',
}

# Schedule downtime
dog.Downtime.create(
    'env:staging',
    start: start_ts,
    end: end_ts,
    recurrence: rrule_recurrence
)

Update a downtime

put https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/{downtime_id}

Overview

Update a single downtime by downtime_id.

Arguments

Path Parameters

Name

Type

Description

downtime_id [required]

integer

ID of the downtime to update.

Request

Body Data (required)

Update a downtime request body.

Expand All

Field

Type

Description

active

boolean

If a scheduled downtime currently exists.

canceled

int64

If a scheduled downtime is canceled.

creator_id

int32

User ID of the downtime creator.

disabled

boolean

If a downtime has been disabled.

downtime_type

int32

0 for a downtime applied on * or all, 1 when the downtime is only scoped to hosts, or 2 when the downtime is scoped to anything but hosts.

end

int64

POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely until you cancel it.

int64

The downtime ID.

message

string

A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same @username notation as events.

monitor_id

int64

A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.

monitor_tags

[string]

parent_id

int64

ID of the parent Downtime.

recurrence

object

An object defining the recurrence of the downtime.

scope

[string]

start

int64

POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.

timezone

string

The timezone for the downtime.

updater_id

int32

ID of the last user that updated the downtime.

{
  "disabled": false,
  "end": "1412793983",
  "message": "Message on the downtime",
  "monitor_id": "123456",
  "monitor_tags": [
    "*"
  ],
  "parent_id": "123",
  "recurrence": {
    "period": "1",
    "type": "weeks",
    "until_date": "1447786293",
    "until_occurrences": "2",
    "week_days": [
      "Mon",
      "Tue"
    ]
  },
  "scope": [
    "env:staging"
  ],
  "start": "1412792983",
  "timezone": "America/New_York"
}

Response

Expand All

Field

Type

Description

active

boolean

If a scheduled downtime currently exists.

canceled

int64

If a scheduled downtime is canceled.

creator_id

int32

User ID of the downtime creator.

disabled

boolean

If a downtime has been disabled.

downtime_type

int32

0 for a downtime applied on * or all, 1 when the downtime is only scoped to hosts, or 2 when the downtime is scoped to anything but hosts.

end

int64

POSIX timestamp to end the downtime. If not provided, the downtime is in effect indefinitely until you cancel it.

int64

The downtime ID.

message

string

A message to include with notifications for this downtime. Email notifications can be sent to specific users by using the same @username notation as events.

monitor_id

int64

A single monitor to which the downtime applies. If not provided, the downtime applies to all monitors.

monitor_tags

[string]

parent_id

int64

ID of the parent Downtime.

recurrence

object

An object defining the recurrence of the downtime.

scope

[string]

start

int64

POSIX timestamp to start the downtime. If not provided, the downtime starts the moment it is created.

timezone

string

The timezone for the downtime.

updater_id

int32

ID of the last user that updated the downtime.

{
  "active": true,
  "canceled": "1412799983",
  "creator_id": "123456",
  "disabled": false,
  "downtime_type": "2",
  "end": "1412793983",
  "id": "1625",
  "message": "Message on the downtime",
  "monitor_id": "123456",
  "monitor_tags": [
    "*"
  ],
  "parent_id": "123",
  "recurrence": {
    "period": "1",
    "type": "weeks",
    "until_date": "1447786293",
    "until_occurrences": "2",
    "week_days": [
      "Mon",
      "Tue"
    ]
  },
  "scope": [
    "env:staging"
  ],
  "start": "1412792983",
  "timezone": "America/New_York",
  "updater_id": "123456"
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Forbidden

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Downtime not found

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

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

Code Example

curl

                                        # Path parameters
export downtime_id="123456"
# Curl command
curl -X put https://api.datadoghq.comhttps://api.datadoghq.eu/api/v1/downtime/${downtime_id} \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_CLIENT_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_CLIENT_APP_KEY}" \
-d @- << EOF
{}
EOF

                                        