Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GetFindingsStatistics

Lists GuardDuty findings statistics for the specified detector ID.

You must provide either findingStatisticTypes or groupBy parameter, and not both. You can use the maxResults and orderBy parameters only when using groupBy.

There might be regional differences because some flags might not be available in all the Regions where GuardDuty is currently supported. For more information, see Regions and endpoints.

Request Syntax


POST /detector/detectorId/findings/statistics HTTP/1.1
Content-type: application/json

{
   "findingCriteria": { 
      "criterion": { 
         "string" : { 
            "eq": [ "string" ],
            "equals": [ "string" ],
            "greaterThan": number,
            "greaterThanOrEqual": number,
            "gt": number,
            "gte": number,
            "lessThan": number,
            "lessThanOrEqual": number,
            "lt": number,
            "lte": number,
            "neq": [ "string" ],
            "notEquals": [ "string" ]
         }
      }
   },
   "findingStatisticTypes": [ "string" ],
   "groupBy": "string",
   "maxResults": number,
   "orderBy": "string"
}

URI Request Parameters

The request uses the following URI parameters.

detectorId

The ID of the detector whose findings statistics you want to retrieve.

To find the detectorId in the current Region, see the Settings page in the GuardDuty console, or run the ListDetectors API.

Length Constraints: Minimum length of 1. Maximum length of 300.

Required: Yes

Request Body

The request accepts the following data in JSON format.

findingCriteria

Represents the criteria that is used for querying findings.

Type: FindingCriteria object

Required: No

findingStatisticTypes

This parameter has been deprecated.

The types of finding statistics to retrieve.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Valid Values: COUNT_BY_SEVERITY

Required: No

groupBy

Displays the findings statistics grouped by one of the listed valid values.

Type: String

Valid Values: ACCOUNT | DATE | FINDING_TYPE | RESOURCE | SEVERITY

Required: No

maxResults

The maximum number of results to be returned in the response. The default value is 25.

You can use this parameter only with the groupBy parameter.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No

orderBy

Displays the sorted findings in the requested order. The default value of orderBy is DESC.

You can use this parameter only with the groupBy parameter.

Type: String

Valid Values: ASC | DESC

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "findingStatistics": { 
      "countBySeverity": { 
         "string" : number 
      },
      "groupedByAccount": [ 
         { 
            "accountId": "string",
            "lastGeneratedAt": number,
            "totalFindings": number
         }
      ],
      "groupedByDate": [ 
         { 
            "date": number,
            "lastGeneratedAt": number,
            "severity": number,
            "totalFindings": number
         }
      ],
      "groupedByFindingType": [ 
         { 
            "findingType": "string",
            "lastGeneratedAt": number,
            "totalFindings": number
         }
      ],
      "groupedByResource": [ 
         { 
            "accountId": "string",
            "lastGeneratedAt": number,
            "resourceId": "string",
            "resourceType": "string",
            "totalFindings": number
         }
      ],
      "groupedBySeverity": [ 
         { 
            "lastGeneratedAt": number,
            "severity": number,
            "totalFindings": number
         }
      ]
   },
   "nextToken": "string"
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

findingStatistics

The finding statistics object.

Type: FindingStatistics object

nextToken

The pagination parameter to be used on the next list operation to retrieve more items.

This parameter is currently not supported.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

BadRequestException

A bad request exception object.

HTTP Status Code: 400

InternalServerErrorException

An internal server error exception object.

HTTP Status Code: 500