Import an incident

Note: This endpoint is in Preview. If you have any feedback, contact Datadog support.

POST https://api.ap1.datadoghq.com/api/v2/incidents/importhttps://api.ap2.datadoghq.com/api/v2/incidents/importhttps://api.datadoghq.eu/api/v2/incidents/importhttps://api.ddog-gov.com/api/v2/incidents/importhttps://api.us2.ddog-gov.com/api/v2/incidents/importhttps://api.datadoghq.com/api/v2/incidents/importhttps://api.us3.datadoghq.com/api/v2/incidents/importhttps://api.us5.datadoghq.com/api/v2/incidents/import

Overview

Import an incident from an external system. This endpoint allows you to create incidents with historical data such as custom timestamps for detection, declaration, and resolution. Imported incidents do not execute integrations or notification rules. This endpoint requires the incident_write permission.

OAuth apps require the incident_write authorization scope to access this endpoint.

Arguments

Query Strings

Name

Type

Description

include

array

Specifies which related object types to include in the response when importing an incident.

Request

Body Data (required)

Incident import payload.

Expand All

Field

Type

Description

data [required]

object

Incident data for an import request.

attributes [required]

object

The incident's attributes for an import request.

declared

date-time

Timestamp when the incident was declared.

detected

date-time

Timestamp when the incident was detected.

fields

object

A condensed view of the user-defined fields for which to create initial selections.

<any-key>

 <oneOf>

Dynamic fields for which selections can be made, with field names as keys.

Option 1

object

A field with a single value selected.

value

string

The single value selected for this field.

Option 2

object

A field with potentially multiple values selected.

value

[string]

The multiple values selected for this field.

incident_type_uuid

string

A unique identifier that represents the incident type. If not provided, the default incident type is used.

resolved

date-time

Timestamp when the incident was resolved. Can only be set when the state field is set to 'resolved'.

title [required]

string

The title of the incident that summarizes what happened.

visibility

enum

The visibility of the incident. Allowed enum values: organization,private

default: organization

relationships

object

The relationships for an incident import request.

commander_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

declared_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

type [required]

enum

Incident resource type. Allowed enum values: incidents

default: incidents

{
  "data": {
    "type": "incidents",
    "attributes": {
      "title": "Example-Incident",
      "visibility": "organization"
    }
  }
}

Response

CREATED

Response with an incident.

Expand All

Field

Type

Description

data [required]

object

Incident data from an import response.

attributes

object

The incident's attributes from an import response.

archived

date-time

Timestamp when the incident was archived.

case_id

int64

The incident case ID.

created

date-time

Timestamp when the incident was created.

created_by_uuid

string

UUID of the user who created the incident.

creation_idempotency_key

string

A unique key used to ensure idempotent incident creation.

customer_impact_end

date-time

Timestamp when customers were no longer impacted by the incident.

customer_impact_scope

string

A summary of the impact customers experienced during the incident.

customer_impact_start

date-time

Timestamp when customers began to be impacted by the incident.

declared

date-time

Timestamp when the incident was declared.

declared_by_uuid

string

UUID of the user who declared the incident.

detected

date-time

Timestamp when the incident was detected.

fields

object

A condensed view of the user-defined fields attached to incidents.

<any-key>

 <oneOf>

Dynamic fields for which selections can be made, with field names as keys.

Option 1

object

A field with a single value selected.

type

enum

Type of the single value field definitions. Allowed enum values: dropdown,textbox

default: dropdown

value

string

The single value selected for this field.

Option 2

object

A field with potentially multiple values selected.

type

enum

Type of the multiple value field definitions. Allowed enum values: multiselect,textarray,metrictag,autocomplete

default: multiselect

value

[string]

The multiple values selected for this field.

incident_type_uuid

string

A unique identifier that represents an incident type.

is_test

boolean

A flag indicating whether the incident is a test incident.

last_modified_by_uuid

string

UUID of the user who last modified the incident.

modified

date-time

Timestamp when the incident was last modified.

non_datadog_creator

object

Incident's non Datadog creator.

image_48_px

string

Non Datadog creator 48px image.

name

string

Non Datadog creator name.

notification_handles

[object]

Notification handles that are notified of the incident during update.

display_name

string

The name of the notified handle.

handle

string

The handle used for the notification. This includes an email address, Slack channel, or workflow.

public_id

int64

The monotonically increasing integer ID for the incident.

resolved

date-time

Timestamp when the incident's state was last changed from active or stable to resolved or completed.

severity

enum

The incident severity. Allowed enum values: UNKNOWN,SEV-0,SEV-1,SEV-2,SEV-3,SEV-4,SEV-5

state

string

The state of the incident.

title [required]

string

The title of the incident that summarizes what happened.

visibility

string

The incident visibility status.

id [required]

string

The incident's ID.

relationships

object

The incident's relationships from an import response.

attachments

object

A relationship reference for attachments.

data [required]

[object]

An array of incident attachments.

id [required]

string

A unique identifier that represents the attachment.

type [required]

enum

The incident attachment resource type. Allowed enum values: incident_attachments

default: incident_attachments

commander_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

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

declared_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

impacts

object

Relationship to impacts.

data [required]

[object]

An array of incident impacts.

id [required]

string

A unique identifier that represents the impact.

type [required]

enum

The incident impacts type. Allowed enum values: incident_impacts

incident_type

object

Relationship to an incident type.

data [required]

object

Relationship to incident type object.

id [required]

string

The incident type's ID.

type [required]

enum

Incident type resource type. Allowed enum values: incident_types

default: incident_types

integrations

object

A relationship reference for multiple integration metadata objects.

data [required]

[object]

Integration metadata relationship array

id [required]

string

A unique identifier that represents the integration metadata.

type [required]

enum

Integration metadata resource type. Allowed enum values: incident_integrations

default: incident_integrations

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

responders

object

Relationship to incident responders.

data [required]

[object]

An array of incident responders.

id [required]

string

A unique identifier that represents the responder.

type [required]

enum

The incident responders type. Allowed enum values: incident_responders

user_defined_fields

object

Relationship to incident user defined fields.

data [required]

[object]

An array of user defined fields.

id [required]

string

A unique identifier that represents the responder.

type [required]

enum

The incident user defined fields type. Allowed enum values: user_defined_field

type [required]

enum

Incident resource type. Allowed enum values: incidents

default: incidents

included

[ <oneOf>]

Included related resources that the user requested.

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": {
      "archived": "2019-09-19T10:00:00.000Z",
      "case_id": "integer",
      "created": "2025-01-01T00:00:00Z",
      "created_by_uuid": "string",
      "creation_idempotency_key": "string",
      "customer_impact_end": "2019-09-19T10:00:00.000Z",
      "customer_impact_scope": "An example customer impact scope",
      "customer_impact_start": "2019-09-19T10:00:00.000Z",
      "declared": "2025-01-01T00:00:00Z",
      "declared_by_uuid": "string",
      "detected": "2025-01-01T00:00:00Z",
      "fields": {
        "<any-key>": "undefined"
      },
      "incident_type_uuid": "00000000-0000-0000-0000-000000000000",
      "is_test": false,
      "last_modified_by_uuid": "string",
      "modified": "2019-09-19T10:00:00.000Z",
      "non_datadog_creator": {
        "image_48_px": "string",
        "name": "string"
      },
      "notification_handles": [
        {
          "display_name": "Jane Doe",
          "handle": "@test.user@test.com"
        }
      ],
      "public_id": 1,
      "resolved": "2019-09-19T10:00:00.000Z",
      "severity": "UNKNOWN",
      "state": "string",
      "title": "A test incident title",
      "visibility": "string"
    },
    "id": "00000000-0000-0000-1234-000000000000",
    "relationships": {
      "attachments": {
        "data": [
          {
            "id": "00000000-0000-abcd-1000-000000000000",
            "type": "incident_attachments"
          }
        ]
      },
      "commander_user": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "users"
        }
      },
      "created_by_user": {
        "data": {
          "id": "00000000-0000-0000-2345-000000000000",
          "type": "users"
        }
      },
      "declared_by_user": {
        "data": {
          "id": "00000000-0000-0000-2345-000000000000",
          "type": "users"
        }
      },
      "impacts": {
        "data": [
          {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "incident_impacts"
          }
        ]
      },
      "incident_type": {
        "data": {
          "id": "00000000-0000-0000-0000-000000000000",
          "type": "incident_types"
        }
      },
      "integrations": {
        "data": [
          {
            "id": "00000000-abcd-0001-0000-000000000000",
            "type": "incident_integrations"
          }
        ]
      },
      "last_modified_by_user": {
        "data": {
          "id": "00000000-0000-0000-2345-000000000000",
          "type": "users"
        }
      },
      "responders": {
        "data": [
          {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "incident_responders"
          }
        ]
      },
      "user_defined_fields": {
        "data": [
          {
            "id": "00000000-0000-0000-2345-000000000000",
            "type": "user_defined_field"
          }
        ]
      }
    },
    "type": "incidents"
  },
  "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]

[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

                          ## default
# 

# Curl command
curl -X POST "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/import" \ -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": { "declared": "2025-01-01T00:00:00Z", "detected": "2025-01-01T00:00:00Z", "fields": { "severity": { "value": "SEV-5" }, "state": { "value": "active" } }, "incident_type_uuid": "00000000-0000-0000-0000-000000000000", "resolved": "2025-01-01T01:00:00Z", "title": "Imported incident from external system", "visibility": "organization" }, "relationships": { "commander_user": { "data": { "id": "00000000-0000-0000-0000-000000000000", "type": "users" } }, "declared_by_user": { "data": { "id": "00000000-0000-0000-0000-000000000000", "type": "users" } } }, "type": "incidents" } } EOF
// Import an incident returns "CREATED" 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() {
	body := datadogV2.IncidentImportRequest{
		Data: datadogV2.IncidentImportRequestData{
			Type: datadogV2.INCIDENTTYPE_INCIDENTS,
			Attributes: datadogV2.IncidentImportRequestAttributes{
				Title:      "Example-Incident",
				Visibility: datadogV2.INCIDENTIMPORTVISIBILITY_ORGANIZATION.Ptr(),
			},
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.ImportIncident", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewIncidentsApi(apiClient)
	resp, r, err := api.ImportIncident(ctx, body, *datadogV2.NewImportIncidentOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `IncidentsApi.ImportIncident`:\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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// Import an incident returns "CREATED" 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.IncidentImportRequest;
import com.datadog.api.client.v2.model.IncidentImportRequestAttributes;
import com.datadog.api.client.v2.model.IncidentImportRequestData;
import com.datadog.api.client.v2.model.IncidentImportResponse;
import com.datadog.api.client.v2.model.IncidentImportVisibility;
import com.datadog.api.client.v2.model.IncidentType;

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

    IncidentImportRequest body =
        new IncidentImportRequest()
            .data(
                new IncidentImportRequestData()
                    .type(IncidentType.INCIDENTS)
                    .attributes(
                        new IncidentImportRequestAttributes()
                            .title("Example-Incident")
                            .visibility(IncidentImportVisibility.ORGANIZATION)));

    try {
      IncidentImportResponse result = apiInstance.importIncident(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling IncidentsApi#importIncident");
      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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
"""
Import an incident returns "CREATED" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.incidents_api import IncidentsApi
from datadog_api_client.v2.model.incident_import_request import IncidentImportRequest
from datadog_api_client.v2.model.incident_import_request_attributes import IncidentImportRequestAttributes
from datadog_api_client.v2.model.incident_import_request_data import IncidentImportRequestData
from datadog_api_client.v2.model.incident_import_visibility import IncidentImportVisibility
from datadog_api_client.v2.model.incident_type import IncidentType

body = IncidentImportRequest(
    data=IncidentImportRequestData(
        type=IncidentType.INCIDENTS,
        attributes=IncidentImportRequestAttributes(
            title="Example-Incident",
            visibility=IncidentImportVisibility.ORGANIZATION,
        ),
    ),
)

configuration = Configuration()
configuration.unstable_operations["import_incident"] = True
with ApiClient(configuration) as api_client:
    api_instance = IncidentsApi(api_client)
    response = api_instance.import_incident(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.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# Import an incident returns "CREATED" response

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

body = DatadogAPIClient::V2::IncidentImportRequest.new({
  data: DatadogAPIClient::V2::IncidentImportRequestData.new({
    type: DatadogAPIClient::V2::IncidentType::INCIDENTS,
    attributes: DatadogAPIClient::V2::IncidentImportRequestAttributes.new({
      title: "Example-Incident",
      visibility: DatadogAPIClient::V2::IncidentImportVisibility::ORGANIZATION,
    }),
  }),
})
p api_instance.import_incident(body)

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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// Import an incident returns "CREATED" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_incidents::ImportIncidentOptionalParams;
use datadog_api_client::datadogV2::api_incidents::IncidentsAPI;
use datadog_api_client::datadogV2::model::IncidentImportRequest;
use datadog_api_client::datadogV2::model::IncidentImportRequestAttributes;
use datadog_api_client::datadogV2::model::IncidentImportRequestData;
use datadog_api_client::datadogV2::model::IncidentImportVisibility;
use datadog_api_client::datadogV2::model::IncidentType;

#[tokio::main]
async fn main() {
    let body = IncidentImportRequest::new(IncidentImportRequestData::new(
        IncidentImportRequestAttributes::new("Example-Incident".to_string())
            .visibility(IncidentImportVisibility::ORGANIZATION),
        IncidentType::INCIDENTS,
    ));
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ImportIncident", true);
    let api = IncidentsAPI::with_config(configuration);
    let resp = api
        .import_incident(body, ImportIncidentOptionalParams::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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Import an incident returns "CREATED" response
 */

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

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

const params: v2.IncidentsApiImportIncidentRequest = {
  body: {
    data: {
      type: "incidents",
      attributes: {
        title: "Example-Incident",
        visibility: "organization",
      },
    },
  },
};

apiInstance
  .importIncident(params)
  .then((data: v2.IncidentImportResponse) => {
    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="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"