List governance 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/governance/insightshttps://api.ap2.datadoghq.com/api/v2/governance/insightshttps://api.datadoghq.eu/api/v2/governance/insightshttps://api.ddog-gov.com/api/v2/governance/insightshttps://api.us2.ddog-gov.com/api/v2/governance/insightshttps://api.uk1.datadoghq.com/api/v2/governance/insightshttps://api.datadoghq.com/api/v2/governance/insightshttps://api.us3.datadoghq.com/api/v2/governance/insightshttps://api.us5.datadoghq.com/api/v2/governance/insights

Overview

Retrieve the list of governance insights available to the organization. By default, only insight metadata is returned; pass withValues=true to also compute and include each insight’s current and previous values. Insights can be filtered by product.

Arguments

Query Strings

Name

Type

Description

withValues

boolean

Whether to compute and include the current and previous value of each insight. Defaults to false, in which case only insight metadata is returned.

orgUuid

string

The UUID of the organization to compute insights for. Defaults to the organization of the authenticated user. Used to retrieve insights for a child organization from a parent organization.

filter[product]

array

Restrict the results to insights belonging to the given products. May be repeated to filter by multiple products. Matching is case-insensitive.

Response

OK

A list of governance insights.

Expand All

Field

Type

Description

data [required]

[object]

An array of governance insight resources.

attributes [required]

object

The attributes of a governance insight.

audit_query [required]

object

An audit log query used to compute an insight value.

compute [required]

object

The aggregation applied to an audit log query.

aggregation [required]

string

The aggregation function to apply.

interval [required]

int64

The aggregation time window, in milliseconds.

metric [required]

string

The metric or attribute to aggregate.

rollup

string

An optional secondary aggregation applied to the audit query result.

indexes [required]

[string]

The audit log indexes the query runs against.

query [required]

string

The audit log search query string.

source [required]

string

The data source the query runs against.

best_practice [required]

object

The best practice associated with an insight. Populated with the first active best practice matched to the insight; null when no best practice is attached.

category [required]

string

The value driver the best practice is grouped under, such as access_governance, security, compliance, or operational_hygiene.

deep_link [required]

string

A relative link to the configuration page where the best practice can be acted upon.

description [required]

string

The full rationale and guidance for the best practice.

detection_type

string

An optional association to a control's detection type. null when not associated with a control.

id [required]

string

The unique identifier of the best practice.

impact [required]

string

The expected impact of following the best practice.

impact_hint [required]

int64

A priority hint for ordering best practices by expected impact. Lower values indicate higher priority.

permissions [required]

[string]

The permissions required for the user to act on the best practice.

status [required]

string

Whether the best practice is currently active or deprecated.

summary [required]

string

A one-line explanation of why this best practice matters.

title [required]

string

A short, human-readable name for the best practice.

trigger_condition [required]

string

The condition that surfaces the best practice. For an insight trigger, the insight slug; for a static trigger, a descriptive condition key.

trigger_type [required]

string

How the best practice is surfaced. insight ties it to an insight; static surfaces it unless its condition is met.

deep_link [required]

string

A relative link to the product surface where the insight can be acted upon.

description [required]

string

A human-readable description of what the insight measures.

display_name [required]

string

Human-readable name of the insight.

event_query [required]

object

An event query used to compute an insight value.

compute

object

The aggregation applied to an event query.

aggregation [required]

string

The aggregation function to apply.

interval [required]

int64

The aggregation time window, in milliseconds.

indexes [required]

[string]

The event indexes the query runs against.

query [required]

string

The event search query string.

metric_query [required]

object

A metric query used to compute an insight value.

query [required]

string

The query string.

reducer [required]

string

How the query result series is reduced to a single value.

source [required]

string

The data source the query runs against.

old_value [required]

double

The value of the insight over the previous comparison window. null when values were not requested or could not be computed.

percentage_query [required]

object

A percentage query that computes an insight value as a ratio of two metric queries.

denominator_query [required]

object

A metric query used to compute an insight value.

query [required]

string

The query string.

reducer [required]

string

How the query result series is reduced to a single value.

source [required]

string

The data source the query runs against.

numerator_query [required]

object

A metric query used to compute an insight value.

query [required]

string

The query string.

reducer [required]

string

How the query result series is reduced to a single value.

source [required]

string

The data source the query runs against.

product [required]

string

The product the insight belongs to.

query_config

object

Query execution context that allows the frontend to execute insight queries directly.

chart_type

string

The chart type the frontend should use to render the insight.

comparison_shift [required]

string

The window used for the previous value comparison, for example week or month.

default_value

int64

The default value to display when no data is available.

directionality

string

Whether an increase in the value is good, bad, or neutral. One of neutral, increase_better, or decrease_better.

effective_time_window_days [required]

int64

The number of days the insight value is computed over.

sort_order

int64

The relative order in which the insight should be displayed.

state [required]

string

The state of the insight. A critical insight receives extra UI treatment to draw attention to it.

sub_product [required]

string

The sub-product the insight belongs to, if any.

time_range [required]

string

The time range the insight value is computed over, if applicable.

unit_name [required]

string

The unit that the insight's value is measured in.

usage_query [required]

object

A usage query used to compute an insight value.

query [required]

string

The usage query string.

reducer [required]

string

How the query result series is reduced to a single value.

value [required]

double

The current value of the insight. null when values were not requested or could not be computed.

id [required]

string

The unique identifier of the insight.

type [required]

enum

JSON:API resource type for a governance insight. Allowed enum values: insight

{
  "data": [
    {
      "attributes": {
        "audit_query": {
          "compute": {
            "aggregation": "cardinality",
            "interval": 86400000,
            "metric": "@usr.id",
            "rollup": ""
          },
          "indexes": [
            "main"
          ],
          "query": "@evt.name:Dashboard",
          "source": "audit"
        },
        "best_practice": {
          "category": "access_governance",
          "deep_link": "/organization-settings/users?status=inactive",
          "description": "Review and deactivate users who have not logged in within the last 90 days.",
          "detection_type": null,
          "id": "bp_monitor_inactive_users",
          "impact": "Reduces unauthorized access risk.",
          "impact_hint": 1,
          "permissions": [
            "user_access_manage"
          ],
          "status": "active",
          "summary": "Inactive users with access increase your security surface area.",
          "title": "Monitor inactive users",
          "trigger_condition": "active_users",
          "trigger_type": "insight"
        },
        "deep_link": "",
        "description": "Number of users who have used the Dashboard in the last 30 days",
        "display_name": "Active Dashboards",
        "event_query": {
          "compute": {
            "aggregation": "count",
            "interval": 86400000
          },
          "indexes": [
            "main"
          ],
          "query": "source:cloudtrail"
        },
        "metric_query": {
          "query": "avg:system.cpu.user{*}",
          "reducer": "avg",
          "source": "metrics"
        },
        "old_value": 3274,
        "percentage_query": {
          "denominator_query": {
            "query": "avg:system.cpu.user{*}",
            "reducer": "avg",
            "source": "metrics"
          },
          "numerator_query": {
            "query": "avg:system.cpu.user{*}",
            "reducer": "avg",
            "source": "metrics"
          }
        },
        "product": "Usage",
        "query_config": {
          "chart_type": "line",
          "comparison_shift": "month",
          "default_value": 0,
          "directionality": "neutral",
          "effective_time_window_days": 30
        },
        "sort_order": 1,
        "state": "critical",
        "sub_product": "Indexes",
        "time_range": "month",
        "unit_name": "active dashboards",
        "usage_query": {
          "query": "logs_indexed_events",
          "reducer": "sum"
        },
        "value": 3601
      },
      "id": "498ee21f-8037-48b8-a961-a488692902f4",
      "type": "insight"
    }
  ]
}

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

Unauthorized

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

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/governance/insights" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List governance insights returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.governance_insights_api import GovernanceInsightsApi

configuration = Configuration()
configuration.unstable_operations["list_governance_insights"] = True
with ApiClient(configuration) as api_client:
    api_instance = GovernanceInsightsApi(api_client)
    response = api_instance.list_governance_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 governance insights returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_governance_insights".to_sym] = true
end
api_instance = DatadogAPIClient::V2::GovernanceInsightsAPI.new
p api_instance.list_governance_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 governance 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.ListGovernanceInsights", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewGovernanceInsightsApi(apiClient)
	resp, r, err := api.ListGovernanceInsights(ctx, *datadogV2.NewListGovernanceInsightsOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `GovernanceInsightsApi.ListGovernanceInsights`:\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 governance insights returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.GovernanceInsightsApi;
import com.datadog.api.client.v2.model.GovernanceInsightsResponse;

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

    try {
      GovernanceInsightsResponse result = apiInstance.listGovernanceInsights();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling GovernanceInsightsApi#listGovernanceInsights");
      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 governance insights returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_governance_insights::GovernanceInsightsAPI;
use datadog_api_client::datadogV2::api_governance_insights::ListGovernanceInsightsOptionalParams;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListGovernanceInsights", true);
    let api = GovernanceInsightsAPI::with_config(configuration);
    let resp = api
        .list_governance_insights(ListGovernanceInsightsOptionalParams::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 governance insights returns "OK" response
 */

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

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

apiInstance
  .listGovernanceInsights()
  .then((data: v2.GovernanceInsightsResponse) => {
    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"