---
title: Cancel downtimes by scope
description: Delete all downtimes that match the scope of X.
breadcrumbs: Docs > API > Cancel downtimes by scope
---

> For the complete documentation index, see [llms.txt](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/llms.txt).

# Cancel downtimes by scope

## v1 (deprecated)

| Datadog site      | API endpoint                                                       |
| ----------------- | ------------------------------------------------------------------ |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v1/downtime/cancel/by_scope     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v1/downtime/cancel/by_scope |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v1/downtime/cancel/by_scope |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v1/downtime/cancel/by_scope      |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v1/downtime/cancel/by_scope |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v1/downtime/cancel/by_scope |
| uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v1/downtime/cancel/by_scope |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v1/downtime/cancel/by_scope      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v1/downtime/cancel/by_scope  |

### Overview

Delete all downtimes that match the scope of `X`. **Note:** This only interacts with Downtimes created using v1 endpoints. This endpoint has been deprecated and will not be replaced. Please use v2 endpoints to find and cancel downtimes.

This endpoint requires the `monitors_downtime` permission.

OAuth apps require the `monitors_downtime` authorization [scope](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/scopes.md#downtimes) to access this endpoint.

### Request

#### Body Data (required)

Scope to cancel downtimes for.

{% tabs %}
{% tab label="Model" %}
| Field              | Type   | Description                                                                                                                                                                                                                                                                                   |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| scope [*required*] | string | The scope(s) to which the downtime applies and must be in `key:value` format. 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`). |
{% /tab %}

{% tab label="Example" %}
```json
{
  "scope": "string"
}
```
{% /tab %}
{% /tabs %}

### Response

{% tabs %}
{% tab label="200" %}
OK

{% tabs %}
{% tab label="Model" %}
Object containing array of IDs of canceled downtimes.

| Field         | Type      | Description                         |
| ------------- | --------- | ----------------------------------- |
| cancelled_ids | [integer] | ID of downtimes that were canceled. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "cancelled_ids": [
    123456789,
    123456790
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="400" %}
Bad Request

{% tabs %}
{% tab label="Model" %}
Error response object.

| Field               | Type     | Description                          |
| ------------------- | -------- | ------------------------------------ |
| errors [*required*] | [string] | Array of errors returned by the API. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="403" %}
Forbidden

{% tabs %}
{% tab label="Model" %}
Error response object.

| Field               | Type     | Description                          |
| ------------------- | -------- | ------------------------------------ |
| errors [*required*] | [string] | Array of errors returned by the API. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="404" %}
Downtimes not found

{% tabs %}
{% tab label="Model" %}
Error response object.

| Field               | Type     | Description                          |
| ------------------- | -------- | ------------------------------------ |
| errors [*required*] | [string] | Array of errors returned by the API. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="429" %}
Too many requests

{% tabs %}
{% tab label="Model" %}
Error response object.

| Field               | Type     | Description                          |
| ------------------- | -------- | ------------------------------------ |
| errors [*required*] | [string] | Array of errors returned by the API. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}
{% /tabs %}

### Code Example

{% tabs %}
{% tab label="Curl" %}
```bash
# Set your Datadog site and credentials
export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v1/downtime/cancel/by_scope" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "scope": "string"
}
EOF
```
{% /tab %}

{% tab label="Go" %}
```go
// Cancel downtimes by scope returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV1"
)

func main() {
	// there is a valid "downtime" in the system
	DowntimeScope0 := os.Getenv("DOWNTIME_SCOPE_0")

	body := datadogV1.CancelDowntimesByScopeRequest{
		Scope: DowntimeScope0,
	}
	ctx := datadog.NewDefaultContext(context.Background())
	ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN"))
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV1.NewDowntimesApi(apiClient)
	resp, r, err := api.CancelDowntimesByScope(ctx, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `DowntimesApi.CancelDowntimesByScope`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `DowntimesApi.CancelDowntimesByScope`:\n%s\n", responseContent)
}
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" go run "main.go"
```
{% /tab %}

{% tab label="Java" %}
```java
// Cancel downtimes by scope returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v1.api.DowntimesApi;
import com.datadog.api.client.v1.model.CancelDowntimesByScopeRequest;
import com.datadog.api.client.v1.model.CanceledDowntimesIds;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN"));
    DowntimesApi apiInstance = new DowntimesApi(defaultClient);

    // there is a valid "downtime" in the system
    String DOWNTIME_SCOPE_0 = System.getenv("DOWNTIME_SCOPE_0");

    CancelDowntimesByScopeRequest body =
        new CancelDowntimesByScopeRequest().scope(DOWNTIME_SCOPE_0);

    try {
      CanceledDowntimesIds result = apiInstance.cancelDowntimesByScope(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling DowntimesApi#cancelDowntimesByScope");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" java "Example.java"
```
{% /tab %}

{% tab label="Python" %}
```python
"""
Cancel downtimes by scope returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v1.api.downtimes_api import DowntimesApi
from datadog_api_client.v1.model.cancel_downtimes_by_scope_request import CancelDowntimesByScopeRequest

# there is a valid "downtime" in the system
DOWNTIME_SCOPE_0 = environ["DOWNTIME_SCOPE_0"]

body = CancelDowntimesByScopeRequest(
    scope=DOWNTIME_SCOPE_0,
)

configuration = Configuration()
configuration.access_token = environ["DD_BEARER_TOKEN"]
with ApiClient(configuration) as api_client:
    api_instance = DowntimesApi(api_client)
    response = api_instance.cancel_downtimes_by_scope(body=body)

    print(response)
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" python3 "example.py"
```
{% /tab %}

{% tab label="Ruby" %}
```ruby
# Cancel downtimes by scope returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.access_token = ENV["DD_BEARER_TOKEN"]
end
api_instance = DatadogAPIClient::V1::DowntimesAPI.new

# there is a valid "downtime" in the system
DOWNTIME_SCOPE_0 = ENV["DOWNTIME_SCOPE_0"]

body = DatadogAPIClient::V1::CancelDowntimesByScopeRequest.new({
  scope: DOWNTIME_SCOPE_0,
})
p api_instance.cancel_downtimes_by_scope(body)
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" rb "example.rb"
```
{% /tab %}

{% tab label="Rust" %}
```rust
// Cancel downtimes by scope returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV1::api_downtimes::DowntimesAPI;
use datadog_api_client::datadogV1::model::CancelDowntimesByScopeRequest;

#[tokio::main]
async fn main() {
    // there is a valid "downtime" in the system
    let downtime_scope_0 = std::env::var("DOWNTIME_SCOPE_0").unwrap();
    let body = CancelDowntimesByScopeRequest::new(downtime_scope_0.clone());
    let configuration = datadog::Configuration::new();
    let api = DowntimesAPI::with_config(configuration);
    let resp = api.cancel_downtimes_by_scope(body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
```
{% /tab %}

{% tab label="TypeScript" %}
```typescript
/**
 * Cancel downtimes by scope returns "OK" response
 */

import { client, v1 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration({
  authMethods: {
    AuthZ: {
      accessToken: process.env.DD_BEARER_TOKEN as string,
    },
  },
});
const apiInstance = new v1.DowntimesApi(configuration);

// there is a valid "downtime" in the system
const DOWNTIME_SCOPE_0 = process.env.DOWNTIME_SCOPE_0 as string;

const params: v1.DowntimesApiCancelDowntimesByScopeRequest = {
  body: {
    scope: DOWNTIME_SCOPE_0,
  },
};

apiInstance
  .cancelDowntimesByScope(params)
  .then((data: v1.CanceledDowntimesIds) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>" tsc "example.ts"
```
{% /tab %}

{% tab label="Python [legacy]" %}
```python
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')
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=python-legacy) and then save the example to `example.py` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python "example.py"
```
{% /tab %}

{% tab label="Ruby [legacy]" %}
```ruby
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')
```

#### Instructions

First [install the library and its dependencies](https://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=ruby-legacy) and then save the example to `example.rb` and run following commands:

```bash
DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
```
{% /tab %}
{% /tabs %}