--- title: List findings description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Security Monitoring --- # List findings{% #list-findings %} Copy pageCopied {% tab title="v2" %} **Note**: This endpoint uses the legacy security findings data model and is planned for deprecation. Use the [search security findings endpoint](https://docs.datadoghq.com/api/latest/security-monitoring.md#search-security-findings), which is based on the [new security findings schema](https://docs.datadoghq.com/security/guide/findings-schema.md), to search security findings. 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/posture_management/findings | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/posture_management/findings | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/posture_management/findings | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/posture_management/findings | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/posture_management/findings | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/posture_management/findings | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/posture_management/findings | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/posture_management/findings | ### Overview Get a list of findings. These include both misconfigurations and identity risks. **Note**: To filter and return only identity risks, add the following query parameter: `?filter[tags]=dd_rule_type:ciem` ### Filtering{% #filtering %} Filters can be applied by appending query parameters to the URL. - Using a single filter: `?filter[attribute_key]=attribute_value` - Chaining filters: `?filter[attribute_key]=attribute_value&filter[attribute_key]=attribute_value...` - Filtering on tags: `?filter[tags]=tag_key:tag_value&filter[tags]=tag_key_2:tag_value_2` Here, `attribute_key` can be any of the filter keys described further below. Query parameters of type `integer` support comparison operators (`>`, `>=`, `<`, `<=`). This is particularly useful when filtering by `evaluation_changed_at` or `resource_discovery_timestamp`. For example: `?filter[evaluation_changed_at]=>20123123121`. You can also use the negation operator on strings. For example, use `filter[resource_type]=-aws*` to filter for any non-AWS resources. The operator must come after the equal sign. For example, to filter with the `>=` operator, add the operator after the equal sign: `filter[evaluation_changed_at]=>=1678809373257`. Query parameters must be only among the documented ones and with values of correct types. Duplicated query parameters (e.g. `filter[status]=low&filter[status]=info`) are not allowed. ### Additional extension fields{% #additional-extension-fields %} Additional extension fields are available for some findings. The data is available when you include the query parameter `?detailed_findings=true` in the request. The following fields are available for findings: - `external_id`: The resource external ID related to the finding. - `description`: The description and remediation steps for the finding. - `datadog_link`: The Datadog relative link for the finding. - `ip_addresses`: The list of private IP addresses for the resource related to the finding. ### Response{% #response %} The response includes an array of finding objects, pagination metadata, and a count of items that match the query. Each finding object contains the following: - The finding ID that can be used in a `GetFinding` request to retrieve the full finding details. - Core attributes, including status, evaluation, high-level resource details, muted state, and rule details. - `evaluation_changed_at` and `resource_discovery_date` time stamps. - An array of associated tags. OAuth apps require the `security_monitoring_findings_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#security-monitoring) to access this endpoint. ### Arguments #### Query Strings | Name | Type | Description | | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | page[limit] | integer | Limit the number of findings returned. Must be <= 1000. | | snapshot_timestamp | integer | Return findings for a given snapshot of time (Unix ms). | | page[cursor] | string | Return the next page of findings pointed to by the cursor. | | filter[tags] | string | Return findings that have these associated tags (repeatable). | | filter[evaluation_changed_at] | string | Return findings that have changed from pass to fail or vice versa on a specified date (Unix ms) or date range (using comparison operators). | | filter[muted] | boolean | Set to `true` to return findings that are muted. Set to `false` to return unmuted findings. | | filter[rule_id] | string | Return findings for the specified rule ID. | | filter[rule_name] | string | Return findings for the specified rule. | | filter[resource_type] | string | Return only findings for the specified resource type. | | filter[@resource_id] | string | Return only findings for the specified resource id. | | filter[discovery_timestamp] | string | Return findings that were found on a specified date (Unix ms) or date range (using comparison operators). | | filter[evaluation] | enum | Return only `pass` or `fail` findings. Allowed enum values: `pass, fail` | | filter[status] | enum | Return only findings with the specified status. Allowed enum values: `critical, high, medium, low, info` | | filter[vulnerability_type] | array | Return findings that match the selected vulnerability types (repeatable). | | detailed_findings | boolean | Return additional fields for some findings. | ### Response {% tab title="200" %} OK {% tab title="Model" %} The expected response schema when listing findings. | Parent field | Field | Type | Description | | ------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | [object] | Array of findings. | | data | attributes | object | The JSON:API attributes of the finding. | | attributes | datadog_link | string | The Datadog relative link for this finding. | | attributes | description | string | The description and remediation steps for this finding. | | attributes | evaluation | enum | The evaluation of the finding. Allowed enum values: `pass,fail` | | attributes | evaluation_changed_at | int64 | The date on which the evaluation for this finding changed (Unix ms). | | attributes | external_id | string | The cloud-based ID for the resource related to the finding. | | attributes | mute | object | Information about the mute status of this finding. | | mute | description | string | Additional information about the reason why this finding is muted or unmuted. | | mute | expiration_date | int64 | The expiration date of the mute or unmute action (Unix ms). | | mute | muted | boolean | Whether this finding is muted or unmuted. | | mute | reason | enum | The reason why this finding is muted or unmuted. Allowed enum values: `PENDING_FIX,FALSE_POSITIVE,ACCEPTED_RISK,NO_PENDING_FIX,HUMAN_ERROR,NO_LONGER_ACCEPTED_RISK,OTHER` | | mute | start_date | int64 | The start of the mute period. | | mute | uuid | string | The ID of the user who muted or unmuted this finding. | | attributes | resource | string | The resource name of this finding. | | attributes | resource_discovery_date | int64 | The date on which the resource was discovered (Unix ms). | | attributes | resource_type | string | The resource type of this finding. | | attributes | rule | object | The rule that triggered this finding. | | rule | id | string | The ID of the rule that triggered this finding. | | rule | name | string | The name of the rule that triggered this finding. | | attributes | status | enum | The status of the finding. Allowed enum values: `critical,high,medium,low,info` | | attributes | tags | [string] | The tags associated with this finding. | | attributes | vulnerability_type | enum | The vulnerability type of the finding. Allowed enum values: `misconfiguration,attack_path,identity_risk,api_security` | | data | id | string | The unique ID for this finding. | | data | type | enum | The JSON:API type for findings. Allowed enum values: `finding` | | | meta [*required*] | object | Metadata for pagination. | | meta | page | object | Pagination and findings count information. | | page | cursor | string | The cursor used to paginate requests. | | page | total_filtered_count | int64 | The total count of findings after the filter has been applied. | | meta | snapshot_timestamp | int64 | The point in time corresponding to the listed findings. | {% /tab %} {% tab title="Example" %} ```json { "data": [ { "attributes": { "datadog_link": "/security/compliance?panels=cpfinding%7Cevent%7CruleId%3Adef-000-u5t%7CresourceId%3Ae8c9ab7c52ebd7bf2fdb4db641082d7d%7CtabId%3Aoverview", "description": "## Remediation\n\n1. In the console, go to **Storage Account**.\n2. For each Storage Account, navigate to **Data Protection**.\n3. Select **Set soft delete enabled** and enter the number of days to retain soft deleted data.", "evaluation": "pass", "evaluation_changed_at": 1678721573794, "external_id": "arn:aws:s3:::my-example-bucket", "mute": { "description": "To be resolved later", "expiration_date": 1778721573794, "muted": true, "reason": "ACCEPTED_RISK", "start_date": 1678721573794, "uuid": "e51c9744-d158-11ec-ad23-da7ad0900002" }, "resource": "my_resource_name", "resource_discovery_date": 1678721573794, "resource_type": "azure_storage_account", "rule": { "id": "dv2-jzf-41i", "name": "Soft delete is enabled for Azure Storage" }, "status": "critical", "tags": [ "cloud_provider:aws", "myTag:myValue" ], "vulnerability_type": "misconfiguration" }, "id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==", "type": "finding" } ], "meta": { "page": { "cursor": "eyJhZnRlciI6IkFRQUFBWWJiaEJXQS1OY1dqUUFBQUFCQldXSmlhRUpYUVVGQlJFSktkbTlDTUdaWFRVbDNRVUUiLCJ2YWx1ZXMiOlsiY3JpdGljYWwiXX0=", "total_filtered_count": 213 }, "snapshot_timestamp": 1678721573794 } } ``` {% /tab %} {% /tab %} {% tab title="400" %} Bad Request: The server cannot process the request due to invalid syntax in the 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: Access denied {% 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="404" %} Not Found: The requested finding cannot be found. {% 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: The rate limit set by the API has been exceeded. {% 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/posture_management/findings" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" ##### ```python """ List findings returns "OK" response """ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi configuration = Configuration() configuration.unstable_operations["list_findings"] = True with ApiClient(configuration) as api_client: api_instance = SecurityMonitoringApi(api_client) response = api_instance.list_findings() 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 findings returns "OK" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.unstable_operations["v2.list_findings".to_sym] = true end api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new p api_instance.list_findings() ``` #### 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 findings 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.ListFindings", true) apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewSecurityMonitoringApi(apiClient) resp, r, err := api.ListFindings(ctx, *datadogV2.NewListFindingsOptionalParameters()) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.ListFindings`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.ListFindings`:\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 findings returns "OK" response import com.datadog.api.client.ApiClient; import com.datadog.api.client.ApiException; import com.datadog.api.client.v2.api.SecurityMonitoringApi; import com.datadog.api.client.v2.model.ListFindingsResponse; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setUnstableOperationEnabled("v2.listFindings", true); SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient); try { ListFindingsResponse result = apiInstance.listFindings(); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling SecurityMonitoringApi#listFindings"); 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 findings returns "OK" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_security_monitoring::ListFindingsOptionalParams; use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI; #[tokio::main] async fn main() { let mut configuration = datadog::Configuration::new(); configuration.set_unstable_operation_enabled("v2.ListFindings", true); let api = SecurityMonitoringAPI::with_config(configuration); let resp = api .list_findings(ListFindingsOptionalParams::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 findings returns "OK" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration(); configuration.unstableOperations["v2.listFindings"] = true; const apiInstance = new v2.SecurityMonitoringApi(configuration); apiInstance .listFindings() .then((data: v2.ListFindingsResponse) => { 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 %}