--- title: "List findings" method: GET path: "/api/v2/posture_management/findings" tags: ["Security Monitoring"] --- # List findings `GET /api/v2/posture_management/findings` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/posture_management/findings` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` scopes: `security_monitoring_findings_read` 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 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 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 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. ## Query parameters - `page[limit]` integer - `snapshot_timestamp` integer - `page[cursor]` string - `filter[tags]` string - `filter[evaluation_changed_at]` string - `filter[muted]` boolean - `filter[rule_id]` string - `filter[rule_name]` string - `filter[resource_type]` string - `filter[@resource_id]` string - `filter[discovery_timestamp]` string - `filter[evaluation]` 'pass' | 'fail': The evaluation of the finding. - `filter[status]` 'critical' | 'high' | 'medium' | 'low' | 'info': The status of the finding. - `filter[vulnerability_type]` FindingVulnerabilityType[] - `detailed_findings` boolean ## Response `200` OK - ListFindingsResponse: The expected response schema when listing findings. - `data` Finding[], required: Array of findings. - `attributes` FindingAttributes: The JSON:API attributes of the finding. - `datadog_link` string: The Datadog relative link for this finding. - `description` string: The description and remediation steps for this finding. - `evaluation` 'pass' | 'fail': The evaluation of the finding. - `evaluation_changed_at` integer: The date on which the evaluation for this finding changed (Unix ms). - `external_id` string: The cloud-based ID for the resource related to the finding. - `mute` FindingMute: Information about the mute status of this finding. - `description` string: Additional information about the reason why this finding is muted or unmuted. - `expiration_date` integer: The expiration date of the mute or unmute action (Unix ms). - `muted` boolean: Whether this finding is muted or unmuted. - `reason` 'PENDING_FIX' | 'FALSE_POSITIVE' | 'ACCEPTED_RISK' | 'NO_PENDING_FIX' | 'HUMAN_ERROR' | 'NO_LONGER_ACCEPTED_RISK' | 'OTHER': The reason why this finding is muted or unmuted. - `start_date` integer: The start of the mute period. - `uuid` string: The ID of the user who muted or unmuted this finding. - `resource` string: The resource name of this finding. - `resource_discovery_date` integer: The date on which the resource was discovered (Unix ms). - `resource_type` string: The resource type of this finding. - `rule` FindingRule: The rule that triggered this finding. - `id` string: The ID of the rule that triggered this finding. - `name` string: The name of the rule that triggered this finding. - `status` 'critical' | 'high' | 'medium' | 'low' | 'info': The status of the finding. - `tags` string[]: The tags associated with this finding. - `vulnerability_type` 'misconfiguration' | 'attack_path' | 'identity_risk' | 'api_security': The vulnerability type of the finding. - `id` string: The unique ID for this finding. - `type` 'finding': The JSON:API type for findings. - `meta` ListFindingsMeta, required: Metadata for pagination. - `page` ListFindingsPage: Pagination and findings count information. - `cursor` string: The cursor used to paginate requests. - `total_filtered_count` integer: The total count of findings after the filter has been applied. - `snapshot_timestamp` integer: The point in time corresponding to the listed findings. ## Other responses - `400`: Bad Request: The server cannot process the request due to invalid syntax in the request. - `403`: Forbidden: Access denied - `404`: Not Found: The requested finding cannot be found. - `429`: Too many requests: The rate limit set by the API has been exceeded. --- [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)