--- title: "List governance insights" method: GET path: "/api/v2/governance/insights" tags: ["Governance Insights"] --- # List governance insights `GET /api/v2/governance/insights` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/governance/insights` - Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` 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. ## Query parameters - `withValues` boolean - `orgUuid` string - `filter[product]` string[] ## Response `200` OK - GovernanceInsightsResponse: A list of governance insights. - `data` GovernanceInsightData[], required: An array of governance insight resources. - `attributes` GovernanceInsightAttributes, required: The attributes of a governance insight. - `audit_query` GovernanceInsightAuditQuery, required: An audit log query used to compute an insight value. - `compute` GovernanceInsightAuditCompute, required: The aggregation applied to an audit log query. - `aggregation` string, required: The aggregation function to apply. - `interval` integer, required: The aggregation time window, in milliseconds. - `metric` string, required: The metric or attribute to aggregate. - `rollup` string: An optional secondary aggregation applied to the audit query result. - `indexes` string[], required: The audit log indexes the query runs against. - `query` string, required: The audit log search query string. - `source` string, required: The data source the query runs against. - `best_practice` GovernanceBestPracticeDefinition, required: 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` string, required: The value driver the best practice is grouped under, such as `access_governance`, `security`, `compliance`, or `operational_hygiene`. - `deep_link` string, required: A relative link to the configuration page where the best practice can be acted upon. - `description` string, required: The full rationale and guidance for the best practice. - `detection_type` string, nullable: An optional association to a control's detection type. `null` when not associated with a control. - `id` string, required: The unique identifier of the best practice. - `impact` string, required: The expected impact of following the best practice. - `impact_hint` integer, required: A priority hint for ordering best practices by expected impact. Lower values indicate higher priority. - `permissions` string[], required: The permissions required for the user to act on the best practice. - `status` string, required: Whether the best practice is currently `active` or `deprecated`. - `summary` string, required: A one-line explanation of why this best practice matters. - `title` string, required: A short, human-readable name for the best practice. - `trigger_condition` string, required: The condition that surfaces the best practice. For an `insight` trigger, the insight slug; for a `static` trigger, a descriptive condition key. - `trigger_type` string, required: How the best practice is surfaced. `insight` ties it to an insight; `static` surfaces it unless its condition is met. - `deep_link` string, required: A relative link to the product surface where the insight can be acted upon. - `description` string, required: A human-readable description of what the insight measures. - `display_name` string, required: Human-readable name of the insight. - `event_query` GovernanceInsightEventQuery, required: An event query used to compute an insight value. - `compute` GovernanceInsightEventCompute: The aggregation applied to an event query. - `aggregation` string, required: The aggregation function to apply. - `interval` integer, required: The aggregation time window, in milliseconds. - `indexes` string[], required: The event indexes the query runs against. - `query` string, required: The event search query string. - `metric_query` GovernanceInsightMetricQuery, required: A metric query used to compute an insight value. - `query` string, required: The query string. - `reducer` string, required: How the query result series is reduced to a single value. - `source` string, required: The data source the query runs against. - `old_value` number, double, nullable, required: The value of the insight over the previous comparison window. `null` when values were not requested or could not be computed. - `percentage_query` GovernanceInsightPercentageQuery, required: A percentage query that computes an insight value as a ratio of two metric queries. - `denominator_query` GovernanceInsightMetricQuery, required: A metric query used to compute an insight value. - `query` string, required: The query string. - `reducer` string, required: How the query result series is reduced to a single value. - `source` string, required: The data source the query runs against. - `numerator_query` GovernanceInsightMetricQuery, required: A metric query used to compute an insight value. - `query` string, required: The query string. - `reducer` string, required: How the query result series is reduced to a single value. - `source` string, required: The data source the query runs against. - `product` string, required: The product the insight belongs to. - `query_config` GovernanceInsightQueryConfig: 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` string, required: The window used for the previous value comparison, for example `week` or `month`. - `default_value` integer: 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` integer, required: The number of days the insight value is computed over. - `sort_order` integer: The relative order in which the insight should be displayed. - `state` string, required: The state of the insight. A `critical` insight receives extra UI treatment to draw attention to it. - `sub_product` string, required: The sub-product the insight belongs to, if any. - `time_range` string, required: The time range the insight value is computed over, if applicable. - `unit_name` string, required: The unit that the insight's value is measured in. - `usage_query` GovernanceInsightUsageQuery, required: A usage query used to compute an insight value. - `query` string, required: The usage query string. - `reducer` string, required: How the query result series is reduced to a single value. - `value` number, double, nullable, required: The current value of the insight. `null` when values were not requested or could not be computed. - `id` string, required: The unique identifier of the insight. - `type` 'insight', required: JSON:API resource type for a governance insight. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `429`: Too many requests --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)