:doc:`GuardDuty <../../guardduty>` / Client / get_findings_statistics

***********************
get_findings_statistics
***********************



.. py:method:: GuardDuty.Client.get_findings_statistics(**kwargs)

  

  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 <https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_regions.html>`__.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/guardduty-2017-11-28/GetFindingsStatistics>`_  


  **Request Syntax**
  ::

    response = client.get_findings_statistics(
        DetectorId='string',
        FindingStatisticTypes=[
            'COUNT_BY_SEVERITY',
        ],
        FindingCriteria={
            'Criterion': {
                'string': {
                    'Eq': [
                        'string',
                    ],
                    'Neq': [
                        'string',
                    ],
                    'Gt': 123,
                    'Gte': 123,
                    'Lt': 123,
                    'Lte': 123,
                    'Equals': [
                        'string',
                    ],
                    'NotEquals': [
                        'string',
                    ],
                    'GreaterThan': 123,
                    'GreaterThanOrEqual': 123,
                    'LessThan': 123,
                    'LessThanOrEqual': 123,
                    'Matches': [
                        'string',
                    ],
                    'NotMatches': [
                        'string',
                    ]
                }
            }
        },
        GroupBy='ACCOUNT'|'DATE'|'FINDING_TYPE'|'RESOURCE'|'SEVERITY',
        OrderBy='ASC'|'DESC',
        MaxResults=123
    )
    
  :type DetectorId: string
  :param DetectorId: **[REQUIRED]** 

    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 <https://docs.aws.amazon.com/guardduty/latest/APIReference/API_ListDetectors.html>`__ API.

    

  
  :type FindingStatisticTypes: list
  :param FindingStatisticTypes: 

    The types of finding statistics to retrieve.

    

  
    - *(string) --* 

    

  :type FindingCriteria: dict
  :param FindingCriteria: 

    Represents the criteria that is used for querying findings.

    

  
    - **Criterion** *(dict) --* 

      Represents a map of finding properties that match specified conditions and values when querying findings.

      

    
      - *(string) --* 

      
        - *(dict) --* 

          Contains information about the condition.

          

        
          - **Eq** *(list) --* 

            Represents the *equal* condition to be applied to a single field when querying for findings.

            

          
            - *(string) --* 

            
        
          - **Neq** *(list) --* 

            Represents the *not equal* condition to be applied to a single field when querying for findings.

            

          
            - *(string) --* 

            
        
          - **Gt** *(integer) --* 

            Represents a *greater than* condition to be applied to a single field when querying for findings.

            

          
          - **Gte** *(integer) --* 

            Represents a *greater than or equal* condition to be applied to a single field when querying for findings.

            

          
          - **Lt** *(integer) --* 

            Represents a *less than* condition to be applied to a single field when querying for findings.

            

          
          - **Lte** *(integer) --* 

            Represents a *less than or equal* condition to be applied to a single field when querying for findings.

            

          
          - **Equals** *(list) --* 

            Represents an *equal*  condition to be applied to a single field when querying for findings.

            

          
            - *(string) --* 

            
        
          - **NotEquals** *(list) --* 

            Represents a *not equal*  condition to be applied to a single field when querying for findings.

            

          
            - *(string) --* 

            
        
          - **GreaterThan** *(integer) --* 

            Represents a *greater than* condition to be applied to a single field when querying for findings.

            

          
          - **GreaterThanOrEqual** *(integer) --* 

            Represents a *greater than or equal* condition to be applied to a single field when querying for findings.

            

          
          - **LessThan** *(integer) --* 

            Represents a *less than* condition to be applied to a single field when querying for findings.

            

          
          - **LessThanOrEqual** *(integer) --* 

            Represents a *less than or equal* condition to be applied to a single field when querying for findings.

            

          
          - **Matches** *(list) --* 

            Represents the *match* condition to be applied to a single field when querying for findings.

             

            .. note::

              

              The *matches* condition is available only for create-filter and update-filter APIs.

              

            

          
            - *(string) --* 

            
        
          - **NotMatches** *(list) --* 

            Represents the *not match* condition to be applied to a single field when querying for findings.

             

            .. note::

              

              The *not-matches* condition is available only for create-filter and update-filter APIs.

              

            

          
            - *(string) --* 

            
        
        
  

  
  :type GroupBy: string
  :param GroupBy: 

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

    

  
  :type OrderBy: string
  :param 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 MaxResults: integer
  :param 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.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'FindingStatistics': {
              'CountBySeverity': {
                  'string': 123
              },
              'GroupedByAccount': [
                  {
                      'AccountId': 'string',
                      'LastGeneratedAt': datetime(2015, 1, 1),
                      'TotalFindings': 123
                  },
              ],
              'GroupedByDate': [
                  {
                      'Date': datetime(2015, 1, 1),
                      'LastGeneratedAt': datetime(2015, 1, 1),
                      'Severity': 123.0,
                      'TotalFindings': 123
                  },
              ],
              'GroupedByFindingType': [
                  {
                      'FindingType': 'string',
                      'LastGeneratedAt': datetime(2015, 1, 1),
                      'TotalFindings': 123
                  },
              ],
              'GroupedByResource': [
                  {
                      'AccountId': 'string',
                      'LastGeneratedAt': datetime(2015, 1, 1),
                      'ResourceId': 'string',
                      'ResourceType': 'string',
                      'TotalFindings': 123
                  },
              ],
              'GroupedBySeverity': [
                  {
                      'LastGeneratedAt': datetime(2015, 1, 1),
                      'Severity': 123.0,
                      'TotalFindings': 123
                  },
              ]
          },
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **FindingStatistics** *(dict) --* 

        The finding statistics object.

        
        

        - **CountBySeverity** *(dict) --* 

          Represents a list of map of severity to count statistics for a set of findings.

          
          

          - *(string) --* 
            

            - *(integer) --* 
      
    
        

        - **GroupedByAccount** *(list) --* 

          Represents a list of map of accounts with a findings count associated with each account.

          
          

          - *(dict) --* 

            Represents a list of map of accounts with the number of findings associated with each account.

            
            

            - **AccountId** *(string) --* 

              The ID of the Amazon Web Services account.

              
            

            - **LastGeneratedAt** *(datetime) --* 

              The timestamp at which the finding for this account was last generated.

              
            

            - **TotalFindings** *(integer) --* 

              The total number of findings associated with an account.

              
        
      
        

        - **GroupedByDate** *(list) --* 

          Represents a list of map of dates with a count of total findings generated on each date per severity level.

          
          

          - *(dict) --* 

            Represents list a map of dates with a count of total findings generated on each date.

            
            

            - **Date** *(datetime) --* 

              The timestamp when the total findings count is observed.

               

              For example, ``Date`` would look like ``"2024-09-05T17:00:00-07:00"`` whereas ``LastGeneratedAt`` would look like 2024-09-05T17:12:29-07:00".

              
            

            - **LastGeneratedAt** *(datetime) --* 

              The timestamp at which the last finding in the findings count, was generated.

              
            

            - **Severity** *(float) --* 

              The severity of the findings generated on each date.

              
            

            - **TotalFindings** *(integer) --* 

              The total number of findings that were generated per severity level on each date.

              
        
      
        

        - **GroupedByFindingType** *(list) --* 

          Represents a list of map of finding types with a count of total findings generated for each type.

           

          Based on the ``orderBy`` parameter, this request returns either the most occurring finding types or the least occurring finding types. If the ``orderBy`` parameter is ``ASC``, this will represent the least occurring finding types in your account; otherwise, this will represent the most occurring finding types. The default value of ``orderBy`` is ``DESC``.

          
          

          - *(dict) --* 

            Information about each finding type associated with the ``groupedByFindingType`` statistics.

            
            

            - **FindingType** *(string) --* 

              Name of the finding type.

              
            

            - **LastGeneratedAt** *(datetime) --* 

              The timestamp at which this finding type was last generated in your environment.

              
            

            - **TotalFindings** *(integer) --* 

              The total number of findings associated with generated for each distinct finding type.

              
        
      
        

        - **GroupedByResource** *(list) --* 

          Represents a list of map of top resources with a count of total findings.

          
          

          - *(dict) --* 

            Information about each resource type associated with the ``groupedByResource`` statistics.

            
            

            - **AccountId** *(string) --* 

              The ID of the Amazon Web Services account.

              
            

            - **LastGeneratedAt** *(datetime) --* 

              The timestamp at which the statistics for this resource was last generated.

              
            

            - **ResourceId** *(string) --* 

              ID associated with each resource. The following list provides the mapping of the resource type and resource ID.

               

              **Mapping of resource and resource ID**

               

              
              * AccessKey - ``resource.accessKeyDetails.accessKeyId``
               
              * Container - ``resource.containerDetails.id``
               
              * ECSCluster - ``resource.ecsClusterDetails.name``
               
              * EKSCluster - ``resource.eksClusterDetails.name``
               
              * Instance - ``resource.instanceDetails.instanceId``
               
              * KubernetesCluster - ``resource.kubernetesDetails.kubernetesWorkloadDetails.name``
               
              * Lambda - ``resource.lambdaDetails.functionName``
               
              * RDSDBInstance - ``resource.rdsDbInstanceDetails.dbInstanceIdentifier``
               
              * S3Bucket - ``resource.s3BucketDetails.name``
               
              * S3Object - ``resource.s3BucketDetails.name``
              

              
            

            - **ResourceType** *(string) --* 

              The type of resource.

              
            

            - **TotalFindings** *(integer) --* 

              The total number of findings associated with this resource.

              
        
      
        

        - **GroupedBySeverity** *(list) --* 

          Represents a list of map of total findings for each severity level.

          
          

          - *(dict) --* 

            Information about severity level for each finding type.

            
            

            - **LastGeneratedAt** *(datetime) --* 

              The timestamp at which a finding type for a specific severity was last generated.

              
            

            - **Severity** *(float) --* 

              The severity level associated with each finding type.

              
            

            - **TotalFindings** *(integer) --* 

              The total number of findings associated with this severity.

              
        
      
    
      

      - **NextToken** *(string) --* 

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

         

        This parameter is currently not supported.

        
  
  **Exceptions**
  
  *   :py:class:`GuardDuty.Client.exceptions.BadRequestException`

  
  *   :py:class:`GuardDuty.Client.exceptions.InternalServerErrorException`

  