:doc:`SecurityHub <../../securityhub>` / Client / get_findings_trends_v2

**********************
get_findings_trends_v2
**********************



.. py:method:: SecurityHub.Client.get_findings_trends_v2(**kwargs)

  

  Returns findings trend data based on the specified criteria. This operation helps you analyze patterns and changes in findings over time.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/securityhub-2018-10-26/GetFindingsTrendsV2>`_  


  **Request Syntax**
  ::

    response = client.get_findings_trends_v2(
        Filters={
            'CompositeFilters': [
                {
                    'StringFilters': [
                        {
                            'FieldName': 'account_id'|'region'|'finding_types'|'finding_status'|'finding_cve_ids'|'finding_compliance_status'|'finding_control_id'|'finding_class_name'|'finding_provider'|'finding_activity_name',
                            'Filter': {
                                'Value': 'string',
                                'Comparison': 'EQUALS'|'PREFIX'|'NOT_EQUALS'|'PREFIX_NOT_EQUALS'|'CONTAINS'|'NOT_CONTAINS'|'CONTAINS_WORD'
                            }
                        },
                    ],
                    'NestedCompositeFilters': {'... recursive ...'},
                    'Operator': 'AND'|'OR'
                },
            ],
            'CompositeOperator': 'AND'|'OR'
        },
        StartTime=datetime(2015, 1, 1),
        EndTime=datetime(2015, 1, 1),
        NextToken='string',
        MaxResults=123
    )
    
  :type Filters: dict
  :param Filters: 

    The filters to apply to the findings trend data.

    

  
    - **CompositeFilters** *(list) --* 

      A list of composite filters to apply to the findings trend data.

      

    
      - *(dict) --* 

        A filter structure that contains a logical combination of string filters and nested composite filters for findings trend data.

        

      
        - **StringFilters** *(list) --* 

          A list of string filters that apply to findings trend data fields.

          

        
          - *(dict) --* 

            A filter for string-based fields in findings trend data.

            

          
            - **FieldName** *(string) --* 

              The name of the findings field to filter on.

              

            
            - **Filter** *(dict) --* 

              A string filter for filtering Security Hub findings.

              

            
              - **Value** *(string) --* 

                The string filter value. Filter values are case sensitive. For example, the product name for control-based findings is ``Security Hub``. If you provide ``security hub`` as the filter value, there's no match.

                

              
              - **Comparison** *(string) --* 

                The condition to apply to a string value when filtering Security Hub findings.

                 

                To search for values that have the filter value, use one of the following comparison operators:

                 

                
                * To search for values that include the filter value, use ``CONTAINS``. For example, the filter ``Title CONTAINS CloudFront`` matches findings that have a ``Title`` that includes the string CloudFront.
                 
                * To search for values that exactly match the filter value, use ``EQUALS``. For example, the filter ``AwsAccountId EQUALS 123456789012`` only matches findings that have an account ID of ``123456789012``.
                 
                * To search for values that start with the filter value, use ``PREFIX``. For example, the filter ``ResourceRegion PREFIX us`` matches findings that have a ``ResourceRegion`` that starts with ``us``. A ``ResourceRegion`` that starts with a different value, such as ``af``, ``ap``, or ``ca``, doesn't match.
                

                 

                ``CONTAINS``, ``EQUALS``, and ``PREFIX`` filters on the same field are joined by ``OR``. A finding matches if it matches any one of those filters. For example, the filters ``Title CONTAINS CloudFront OR Title CONTAINS CloudWatch`` match a finding that includes either ``CloudFront``, ``CloudWatch``, or both strings in the title.

                 

                To search for values that don’t have the filter value, use one of the following comparison operators:

                 

                
                * To search for values that exclude the filter value, use ``NOT_CONTAINS``. For example, the filter ``Title NOT_CONTAINS CloudFront`` matches findings that have a ``Title`` that excludes the string CloudFront.
                 
                * To search for values other than the filter value, use ``NOT_EQUALS``. For example, the filter ``AwsAccountId NOT_EQUALS 123456789012`` only matches findings that have an account ID other than ``123456789012``.
                 
                * To search for values that don't start with the filter value, use ``PREFIX_NOT_EQUALS``. For example, the filter ``ResourceRegion PREFIX_NOT_EQUALS us`` matches findings with a ``ResourceRegion`` that starts with a value other than ``us``.
                

                 

                ``NOT_CONTAINS``, ``NOT_EQUALS``, and ``PREFIX_NOT_EQUALS`` filters on the same field are joined by ``AND``. A finding matches only if it matches all of those filters. For example, the filters ``Title NOT_CONTAINS CloudFront AND Title NOT_CONTAINS CloudWatch`` match a finding that excludes both ``CloudFront`` and ``CloudWatch`` in the title.

                 

                You can’t have both a ``CONTAINS`` filter and a ``NOT_CONTAINS`` filter on the same field. Similarly, you can't provide both an ``EQUALS`` filter and a ``NOT_EQUALS`` or ``PREFIX_NOT_EQUALS`` filter on the same field. Combining filters in this way returns an error. ``CONTAINS`` filters can only be used with other ``CONTAINS`` filters. ``NOT_CONTAINS`` filters can only be used with other ``NOT_CONTAINS`` filters.

                 

                You can combine ``PREFIX`` filters with ``NOT_EQUALS`` or ``PREFIX_NOT_EQUALS`` filters for the same field. Security Hub first processes the ``PREFIX`` filters, and then the ``NOT_EQUALS`` or ``PREFIX_NOT_EQUALS`` filters.

                 

                For example, for the following filters, Security Hub first identifies findings that have resource types that start with either ``AwsIam`` or ``AwsEc2``. It then excludes findings that have a resource type of ``AwsIamPolicy`` and findings that have a resource type of ``AwsEc2NetworkInterface``.

                 

                
                * ``ResourceType PREFIX AwsIam``
                 
                * ``ResourceType PREFIX AwsEc2``
                 
                * ``ResourceType NOT_EQUALS AwsIamPolicy``
                 
                * ``ResourceType NOT_EQUALS AwsEc2NetworkInterface``
                

                 

                ``CONTAINS`` and ``NOT_CONTAINS`` operators can be used only with automation rules V1. ``CONTAINS_WORD`` operator is only supported in ``GetFindingsV2``, ``GetFindingStatisticsV2``, ``GetResourcesV2``, and ``GetResourceStatisticsV2`` APIs. For more information, see `Automation rules <https://docs.aws.amazon.com/securityhub/latest/userguide/automation-rules.html>`__ in the *Security Hub User Guide*.

                

              
            
          
      
        - **NestedCompositeFilters** *(list) --* 

          A list of nested composite filters that you can use to create complex filter conditions for findings trend data.

          

        
        - **Operator** *(string) --* 

          The logical operator (AND, OR) to apply between the string filters and nested composite filters.

          

        
      
  
    - **CompositeOperator** *(string) --* 

      The logical operator (AND, OR) to apply between multiple composite filters.

      

    
  
  :type StartTime: datetime
  :param StartTime: **[REQUIRED]** 

    The starting timestamp for the time period to analyze findings trends, in ISO 8601 format.

    

  
  :type EndTime: datetime
  :param EndTime: **[REQUIRED]** 

    The ending timestamp for the time period to analyze findings trends, in ISO 8601 format.

    

  
  :type NextToken: string
  :param NextToken: 

    The token to use for paginating results. This value is returned in the response if more results are available.

    

  
  :type MaxResults: integer
  :param MaxResults: 

    The maximum number of trend data points to return in a single response.

    

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

    
    ::

      {
          'Granularity': 'Daily'|'Weekly'|'Monthly',
          'TrendsMetrics': [
              {
                  'Timestamp': datetime(2015, 1, 1),
                  'TrendsValues': {
                      'SeverityTrends': {
                          'Unknown': 123,
                          'Informational': 123,
                          'Low': 123,
                          'Medium': 123,
                          'High': 123,
                          'Critical': 123,
                          'Fatal': 123,
                          'Other': 123
                      }
                  }
              },
          ],
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Granularity** *(string) --* 

        The time interval granularity for the returned trend data.

        
      

      - **TrendsMetrics** *(list) --* 

        The collection of time-series trend metrics, including counts of findings by severity across the specified time period.

        
        

        - *(dict) --* 

          Contains the findings trend metrics data for a specific time point in the requested time period.

          
          

          - **Timestamp** *(datetime) --* 

            The timestamp for this data point in the findings trend metrics.

            
          

          - **TrendsValues** *(dict) --* 

            The finding trend metric values associated with this timestamp, including severity counts.

            
            

            - **SeverityTrends** *(dict) --* 

              The count of findings organized by severity level for this data point in the trend timeline.

              
              

              - **Unknown** *(integer) --* 

                The count of findings with Unknown severity level at this point in the trend timeline.

                
              

              - **Informational** *(integer) --* 

                The count of findings with Informational severity level at this point in the trend timeline.

                
              

              - **Low** *(integer) --* 

                The count of findings with Low severity level at this point in the trend timeline.

                
              

              - **Medium** *(integer) --* 

                The count of findings with Medium severity level at this point in the trend timeline.

                
              

              - **High** *(integer) --* 

                The count of findings with High severity level at this point in the trend timeline.

                
              

              - **Critical** *(integer) --* 

                The count of findings with Critical severity level at this point in the trend timeline.

                
              

              - **Fatal** *(integer) --* 

                The count of findings with Fatal severity level at this point in the trend timeline.

                
              

              - **Other** *(integer) --* 

                The count of findings with severity levels not fitting into the standard categories at this point in the trend timeline.

                
          
        
      
    
      

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

        The token to use for retrieving the next page of results, if more trend data is available.

        
  
  **Exceptions**
  
  *   :py:class:`SecurityHub.Client.exceptions.InternalServerException`

  
  *   :py:class:`SecurityHub.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`SecurityHub.Client.exceptions.ThrottlingException`

  
  *   :py:class:`SecurityHub.Client.exceptions.ValidationException`

  