List global incident handles

Note: This endpoint is in public beta and is subject to change. If you have any feedback, contact Datadog support.

GET https://api.ap1.datadoghq.com/api/v2/incidents/config/global/incident-handleshttps://api.ap2.datadoghq.com/api/v2/incidents/config/global/incident-handleshttps://api.datadoghq.eu/api/v2/incidents/config/global/incident-handleshttps://api.ddog-gov.com/api/v2/incidents/config/global/incident-handleshttps://api.us2.ddog-gov.com/api/v2/incidents/config/global/incident-handleshttps://api.datadoghq.com/api/v2/incidents/config/global/incident-handleshttps://api.us3.datadoghq.com/api/v2/incidents/config/global/incident-handleshttps://api.us5.datadoghq.com/api/v2/incidents/config/global/incident-handles

Overview

Retrieve a list of global incident handles.

Arguments

Query Strings

Name

Type

Description

include

string

Comma-separated list of related resources to include in the response

Response

OK

Response payload for a list of global incident handles, including handle data and related resources.

Expand All

Field

Type

Description

data [required]

[object]

Array of incident handle data objects returned in a list response.

attributes [required]

object

Incident handle attributes for responses

created_at [required]

date-time

Timestamp when the handle was created

fields [required]

object

Dynamic fields associated with the handle

severity

[string]

Severity levels associated with the handle

modified_at [required]

date-time

Timestamp when the handle was last modified

name [required]

string

The handle name

id [required]

string

The ID of the incident handle

relationships

object

Relationships associated with an incident handle response, including linked users and incident type.

commander_user

object

A single relationship object for an incident handle, wrapping the related resource data.

data [required]

object

Relationship data for an incident handle, containing the ID and type of the related resource.

id [required]

string

The ID of the related resource

type [required]

string

The type of the related resource

created_by_user [required]

object

A single relationship object for an incident handle, wrapping the related resource data.

data [required]

object

Relationship data for an incident handle, containing the ID and type of the related resource.

id [required]

string

The ID of the related resource

type [required]

string

The type of the related resource

incident_type [required]

object

A single relationship object for an incident handle, wrapping the related resource data.

data [required]

object

Relationship data for an incident handle, containing the ID and type of the related resource.

id [required]

string

The ID of the related resource

type [required]

string

The type of the related resource

last_modified_by_user [required]

object

A single relationship object for an incident handle, wrapping the related resource data.

data [required]

object

Relationship data for an incident handle, containing the ID and type of the related resource.

id [required]

string

The ID of the related resource

type [required]

string

The type of the related resource

type [required]

enum

Incident handle resource type Allowed enum values: incidents_handles

included

[ <oneOf>]

Included related resources

Option 1

object

User object returned by the API.

attributes

object

Attributes of user object returned by the API.

email

string

Email of the user.

handle

string

Handle of the user.

icon

string

URL of the user's icon.

name

string

Name of the user.

uuid

string

UUID of the user.

id

string

ID of the user.

type

enum

Users resource type. Allowed enum values: users

default: users

Option 2

object

Incident type response data.

attributes

object

Incident type's attributes.

createdAt

date-time

Timestamp when the incident type was created.

createdBy

string

A unique identifier that represents the user that created the incident type.

description

string

Text that describes the incident type.

is_default

boolean

If true, this incident type will be used as the default incident type if a type is not specified during the creation of incident resources.

lastModifiedBy

string

A unique identifier that represents the user that last modified the incident type.

modifiedAt

date-time

Timestamp when the incident type was last modified.

name [required]

string

The name of the incident type.

prefix

string

The string that will be prepended to the incident title across the Datadog app.

id [required]

string

The incident type's ID.

relationships

object

The incident type's resource relationships.

created_by_user

object

Relationship to user.

data [required]

object

Relationship to user object.

id [required]

string

A unique identifier that represents the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

google_meet_configuration

object

A reference to a Google Meet Configuration resource.

data [required]

object

The Google Meet configuration relationship data object.

id [required]

string

The unique identifier of the Google Meet configuration.

type [required]

string

The type of the Google Meet configuration.

last_modified_by_user

object

Relationship to user.

data [required]

object

Relationship to user object.

id [required]

string

A unique identifier that represents the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

microsoft_teams_configuration

object

A reference to a Microsoft Teams Configuration resource.

data [required]

object

The Microsoft Teams configuration relationship data object.

id [required]

string

The unique identifier of the Microsoft Teams configuration.

type [required]

string

The type of the Microsoft Teams configuration.

zoom_configuration

object

A reference to a Zoom configuration resource.

data [required]

object

The Zoom configuration relationship data object.

id [required]

string

The unique identifier of the Zoom configuration.

type [required]

string

The type of the Zoom configuration.

type [required]

enum

Incident type resource type. Allowed enum values: incident_types

default: incident_types

{
  "data": [
    {
      "attributes": {
        "created_at": "2026-01-13T17:15:52.726905Z",
        "fields": {
          "severity": [
            "SEV-1"
          ]
        },
        "modified_at": "2026-01-13T17:15:52.726905Z",
        "name": "@incident-sev-1"
      },
      "id": "12ceee6d-a7c0-4407-bc54-30e54140d7f0",
      "relationships": {
        "commander_user": {
          "data": {
            "id": "f7b538b1-ed7c-4e84-82de-fdf84a539d40",
            "type": "incident_types"
          }
        },
        "created_by_user": {
          "data": {
            "id": "f7b538b1-ed7c-4e84-82de-fdf84a539d40",
            "type": "incident_types"
          }
        },
        "incident_type": {
          "data": {
            "id": "f7b538b1-ed7c-4e84-82de-fdf84a539d40",
            "type": "incident_types"
          }
        },
        "last_modified_by_user": {
          "data": {
            "id": "f7b538b1-ed7c-4e84-82de-fdf84a539d40",
            "type": "incident_types"
          }
        }
      },
      "type": "incidents_handles"
    }
  ],
  "included": [
    {
      "attributes": {
        "email": "string",
        "handle": "string",
        "icon": "string",
        "name": "string",
        "uuid": "string"
      },
      "id": "string",
      "type": "users"
    }
  ]
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "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 GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/incidents/config/global/incident-handles" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List global incident handles returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi

configuration = Configuration()
configuration.unstable_operations["list_global_incident_handles"] = True
with ApiClient(configuration) as api_client:
    api_instance = IncidentsApi(api_client)
    response = api_instance.list_global_incident_handles()

    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.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# List global incident handles returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_global_incident_handles".to_sym] = true
end
api_instance = DatadogAPIClient::V2::IncidentsAPI.new
p api_instance.list_global_incident_handles()

Instructions

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

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// List global incident handles 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/datadogV2"
)

func main() {
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.ListGlobalIncidentHandles", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewIncidentsApi(apiClient)
	resp, r, err := api.ListGlobalIncidentHandles(ctx, *datadogV2.NewListGlobalIncidentHandlesOptionalParameters())

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

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

Instructions

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

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// List global incident handles returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.IncidentsApi;
import com.datadog.api.client.v2.model.IncidentHandlesResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setUnstableOperationEnabled("v2.listGlobalIncidentHandles", true);
    IncidentsApi apiInstance = new IncidentsApi(defaultClient);

    try {
      IncidentHandlesResponse result = apiInstance.listGlobalIncidentHandles();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling IncidentsApi#listGlobalIncidentHandles");
      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 and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
// List global incident handles returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_incidents::IncidentsAPI;
use datadog_api_client::datadogV2::api_incidents::ListGlobalIncidentHandlesOptionalParams;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListGlobalIncidentHandles", true);
    let api = IncidentsAPI::with_config(configuration);
    let resp = api
        .list_global_incident_handles(ListGlobalIncidentHandlesOptionalParams::default())
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * List global incident handles returns "OK" response
 */

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

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.listGlobalIncidentHandles"] = true;
const apiInstance = new v2.IncidentsApi(configuration);

apiInstance
  .listGlobalIncidentHandles()
  .then((data: v2.IncidentHandlesResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

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

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"