List network health insights

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

GET https://api.ap1.datadoghq.com/api/v2/network-health-insightshttps://api.ap2.datadoghq.com/api/v2/network-health-insightshttps://api.datadoghq.eu/api/v2/network-health-insightshttps://api.ddog-gov.com/api/v2/network-health-insightshttps://api.us2.ddog-gov.com/api/v2/network-health-insightshttps://api.uk1.datadoghq.com/api/v2/network-health-insightshttps://api.datadoghq.com/api/v2/network-health-insightshttps://api.us3.datadoghq.com/api/v2/network-health-insightshttps://api.us5.datadoghq.com/api/v2/network-health-insights

Overview

Return network health insights for the organization within the given time window. Insights are produced by analyzing DNS failures pre-classified by network-dns-logger, TLS certificate metrics, and denied security group connections. Each insight identifies the client and server services involved, the type of issue, and the magnitude of the failure observed during the query window. This endpoint requires the network_health_insights_read permission.

Arguments

Query Strings

Name

Type

Description

from

string

Unix timestamp (number of seconds since epoch) of the start of the query window. If not provided, the start of the query window will be 15 minutes before the to timestamp. If neither from nor to are provided, the query window will be [now - 15m, now].

to

string

Unix timestamp (number of seconds since epoch) of the end of the query window. If not provided, the end of the query window will be the current time. If neither from nor to are provided, the query window will be [now - 15m, now].

Response

OK

Response containing a list of network health insights for the organization.

Expand All

Field

Type

Description

data [required]

[object]

Array of network health insights returned for the query window.

attributes [required]

object

Detailed attributes of a network health insight.

account_id

string

AWS account identifier where the certificate is located. Only set for tls-cert insights.

certificate_id

string

ARN or identifier of the certificate. Only set for tls-cert insights.

certificate_lifetime_percent

double

Percentage of the certificate's validity period that has elapsed, ranging from 0 to 100. Only set for tls-cert insights.

client_region

string

AWS region where the client is located. Only set for tls-cert insights.

client_service

string

Name of the service making the request (DNS query or TLS-secured connection). Set to N/A when the client service cannot be determined.

days_until_expiration

int64

Number of days remaining until the certificate expires. Negative values indicate the certificate has already expired. Only set for tls-cert insights.

dns_query

string

Domain name that was being resolved when the DNS failure occurred. Only set for dns insights.

dns_server

string

DNS server that received the failing query. Only set for dns insights.

domain_name

string

Domain name covered by the certificate. Only set for tls-cert insights.

failure_magnitude

int64

Count of failed events observed during the query window. Only set for dns, tcp, and security-group insights.

failure_rate

double

Percentage of requests that failed during the query window, ranging from 0 to 100. Only set for dns, tcp, and security-group insights.

failure_type

enum

Specific failure type within the insight category. For DNS insights: timeout, nxdomain, servfail, or general_failure. For TLS certificate insights: expired or expiring_soon. For security group insights: denied. Allowed enum values: timeout,nxdomain,servfail,general_failure,expired,expiring_soon,denied

loadbalancer_id

string

ARN of the load balancer using the certificate. Only set for tls-cert insights.

server_region

string

AWS region where the server or load balancer is located. Only set for tls-cert insights.

server_service

string

Name of the target service the client was trying to reach.

total_requests

int64

Total number of requests observed during the query window. Provides context for failure_magnitude and failure_rate. Only set for dns, tcp, and security-group insights.

traffic_volume

object

Network traffic volume metrics between the client and server services during the query window.

bytes_read

int64

Total bytes read from the server to the client during the query window.

bytes_written

int64

Total bytes written from the client to the server during the query window.

total_traffic

int64

Sum of bytes written and bytes read across the query window.

type

enum

Category of network health insight. Indicates whether the insight relates to a DNS issue (dns), a TCP issue (tcp), a TLS certificate issue (tls-cert), or a security group denial (security-group). Allowed enum values: dns,tcp,tls-cert,security-group

id [required]

string

Unique identifier for this network health insight.

type [required]

enum

The resource type for network health insights. Always network-health-insights. Allowed enum values: network-health-insights

default: network-health-insights

{
  "data": [
    {
      "attributes": {
        "account_id": "123456789012",
        "certificate_id": "arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-a123-456b-a123-12345678901f",
        "certificate_lifetime_percent": 96.7,
        "client_region": "us-west-2",
        "client_service": "network-logger",
        "days_until_expiration": 3,
        "dns_query": "kafka-broker.internal.domain.com",
        "dns_server": "cluster-dns",
        "domain_name": "api.example.com",
        "failure_magnitude": 150,
        "failure_rate": 91,
        "failure_type": "nxdomain",
        "loadbalancer_id": "arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/my-lb/50dc6c495c0c9188",
        "server_region": "us-east-1",
        "server_service": "kafka",
        "total_requests": 1200,
        "traffic_volume": {
          "bytes_read": 1800000,
          "bytes_written": 2500000,
          "total_traffic": 4300000
        },
        "type": "dns"
      },
      "id": "example-insight-id",
      "type": "network-health-insights"
    }
  ]
}

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"
    }
  ]
}

Forbidden

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"
  ]
}

Internal Server Error

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"
    }
  ]
}

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.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/network-health-insights" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List network health insights returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.network_health_insights_api import NetworkHealthInsightsApi

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

    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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# List network health insights returns "OK" response

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

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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// List network health insights 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.ListNetworkHealthInsights", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewNetworkHealthInsightsApi(apiClient)
	resp, r, err := api.ListNetworkHealthInsights(ctx, *datadogV2.NewListNetworkHealthInsightsOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `NetworkHealthInsightsApi.ListNetworkHealthInsights`:\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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// List network health insights returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.NetworkHealthInsightsApi;
import com.datadog.api.client.v2.model.NetworkHealthInsightsResponse;

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

    try {
      NetworkHealthInsightsResponse result = apiInstance.listNetworkHealthInsights();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println(
          "Exception when calling NetworkHealthInsightsApi#listNetworkHealthInsights");
      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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
// List network health insights returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_network_health_insights::ListNetworkHealthInsightsOptionalParams;
use datadog_api_client::datadogV2::api_network_health_insights::NetworkHealthInsightsAPI;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListNetworkHealthInsights", true);
    let api = NetworkHealthInsightsAPI::with_config(configuration);
    let resp = api
        .list_network_health_insights(ListNetworkHealthInsightsOptionalParams::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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * List network health insights returns "OK" response
 */

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

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

apiInstance
  .listNetworkHealthInsights()
  .then((data: v2.NetworkHealthInsightsResponse) => {
    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.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"