--- title: List network health insights description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Network Health Insights --- # List network health insights{% #list-network-health-insights %} Copy pageCopied {% tab title="v2" %} **Note**: This endpoint is in preview and is subject to change. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/). | Datadog site | API endpoint | | ----------------- | ---------------------------------------------------------------- | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/network-health-insights | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/network-health-insights | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/network-health-insights | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/network-health-insights | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/network-health-insights | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/network-health-insights | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/network-health-insights | | us5.datadoghq.com | GET https://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 {% tab title="200" %} OK {% tab title="Model" %} Response containing a list of network health insights for the organization. | Parent field | Field | Type | Description | | -------------- | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | data [*required*] | [object] | Array of network health insights returned for the query window. | | data | attributes [*required*] | object | Detailed attributes of a network health insight. | | attributes | account_id | string | AWS account identifier where the certificate is located. Only set for `tls-cert` insights. | | attributes | certificate_id | string | ARN or identifier of the certificate. Only set for `tls-cert` insights. | | attributes | 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. | | attributes | client_region | string | AWS region where the client is located. Only set for `tls-cert` insights. | | attributes | 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. | | attributes | 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. | | attributes | dns_query | string | Domain name that was being resolved when the DNS failure occurred. Only set for `dns` insights. | | attributes | dns_server | string | DNS server that received the failing query. Only set for `dns` insights. | | attributes | domain_name | string | Domain name covered by the certificate. Only set for `tls-cert` insights. | | attributes | failure_magnitude | int64 | Count of failed events observed during the query window. Only set for `dns`, `tcp`, and `security-group` insights. | | attributes | 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. | | attributes | 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` | | attributes | loadbalancer_id | string | ARN of the load balancer using the certificate. Only set for `tls-cert` insights. | | attributes | server_region | string | AWS region where the server or load balancer is located. Only set for `tls-cert` insights. | | attributes | server_service | string | Name of the target service the client was trying to reach. | | attributes | 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. | | attributes | traffic_volume | object | Network traffic volume metrics between the client and server services during the query window. | | traffic_volume | bytes_read | int64 | Total bytes read from the server to the client during the query window. | | traffic_volume | bytes_written | int64 | Total bytes written from the client to the server during the query window. | | traffic_volume | total_traffic | int64 | Sum of bytes written and bytes read across the query window. | | attributes | 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` | | data | id [*required*] | string | Unique identifier for this network health insight. | | data | type [*required*] | enum | The resource type for network health insights. Always `network-health-insights`. Allowed enum values: `network-health-insights` | {% /tab %} {% tab title="Example" %} ```json { "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" } ] } ``` {% /tab %} {% /tab %} {% tab title="400" %} Bad Request {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="500" %} Internal Server Error {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \# Curl command curl -X GET "https://api.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}" ##### ```python """ 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](https://docs.datadoghq.com/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" python3 "example.py" ##### ```ruby # 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](https://docs.datadoghq.com/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" rb "example.rb" ##### ```go // 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](https://docs.datadoghq.com/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" go run "main.go" ##### ```java // 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](https://docs.datadoghq.com/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" java "Example.java" ##### ```rust // 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](https://docs.datadoghq.com/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ##### ```typescript /** * 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](https://docs.datadoghq.com/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" tsc "example.ts" {% /tab %}