:doc:`FreeTier <../../freetier>` / Client / get_free_tier_usage

*******************
get_free_tier_usage
*******************



.. py:method:: FreeTier.Client.get_free_tier_usage(**kwargs)

  

  Returns a list of all Free Tier usage objects that match your filters.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/freetier-2023-09-07/GetFreeTierUsage>`_  


  **Request Syntax**
  ::

    response = client.get_free_tier_usage(
        filter={
            'Or': [
                {'... recursive ...'},
            ],
            'And': [
                {'... recursive ...'},
            ],
            'Not': {'... recursive ...'},
            'Dimensions': {
                'Key': 'SERVICE'|'OPERATION'|'USAGE_TYPE'|'REGION'|'FREE_TIER_TYPE'|'DESCRIPTION'|'USAGE_PERCENTAGE',
                'Values': [
                    'string',
                ],
                'MatchOptions': [
                    'EQUALS'|'STARTS_WITH'|'ENDS_WITH'|'CONTAINS'|'GREATER_THAN_OR_EQUAL',
                ]
            }
        },
        maxResults=123,
        nextToken='string'
    )
    
  :type filter: dict
  :param filter: 

    An expression that specifies the conditions that you want each ``FreeTierUsage`` object to meet.

    

  
    - **Or** *(list) --* 

      Return results that match any of the ``Expressions`` that you specified. in the array.

      

    
      - *(dict) --* 

        Use ``Expression`` to filter in the ``GetFreeTierUsage`` API operation.

         

        You can use the following patterns:

         

        
        * Simple dimension values ( ``Dimensions`` root operator)
         
        * Complex expressions with logical operators ( ``AND``, ``NOT``, and ``OR`` root operators).
        

         

        For *simple dimension values*, you can set the dimension name, values, and match type for the filters that you plan to use.

         

        **Example for simple dimension values**

         

        You can filter to match exactly for ``REGION==us-east-1 OR REGION==us-west-1``.

         

        The corresponding ``Expression`` appears like the following: ``{ "Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ], "MatchOptions": ["EQUALS"] } }``

         

        As shown in the previous example, lists of dimension values are combined with ``OR`` when you apply the filter.

         

        For *complex expressions with logical operators*, you can have nested expressions to use the logical operators and specify advanced filtering.

         

        **Example for complex expressions with logical operators**

         

        You can filter by ``((REGION == us-east-1 OR REGION == us-west-1) OR (SERVICE CONTAINS AWSLambda)) AND (USAGE_TYPE !CONTAINS DataTransfer)``.

         

        The corresponding ``Expression`` appears like the following: ``{ "And": [ {"Or": [ {"Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ], "MatchOptions": ["EQUALS"] }}, {"Dimensions": { "Key": "SERVICE", "Values": ["AWSLambda"], "MatchOptions": ["CONTAINS"] } } ]}, {"Not": {"Dimensions": { "Key": "USAGE_TYPE", "Values": ["DataTransfer"], "MatchOptions": ["CONTAINS"] }}} ] }``

         

        In the following **Contents**, you must specify exactly one of the following root operators.

        

      
  
    - **And** *(list) --* 

      Return results that match all ``Expressions`` that you specified in the array.

      

    
      - *(dict) --* 

        Use ``Expression`` to filter in the ``GetFreeTierUsage`` API operation.

         

        You can use the following patterns:

         

        
        * Simple dimension values ( ``Dimensions`` root operator)
         
        * Complex expressions with logical operators ( ``AND``, ``NOT``, and ``OR`` root operators).
        

         

        For *simple dimension values*, you can set the dimension name, values, and match type for the filters that you plan to use.

         

        **Example for simple dimension values**

         

        You can filter to match exactly for ``REGION==us-east-1 OR REGION==us-west-1``.

         

        The corresponding ``Expression`` appears like the following: ``{ "Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ], "MatchOptions": ["EQUALS"] } }``

         

        As shown in the previous example, lists of dimension values are combined with ``OR`` when you apply the filter.

         

        For *complex expressions with logical operators*, you can have nested expressions to use the logical operators and specify advanced filtering.

         

        **Example for complex expressions with logical operators**

         

        You can filter by ``((REGION == us-east-1 OR REGION == us-west-1) OR (SERVICE CONTAINS AWSLambda)) AND (USAGE_TYPE !CONTAINS DataTransfer)``.

         

        The corresponding ``Expression`` appears like the following: ``{ "And": [ {"Or": [ {"Dimensions": { "Key": "REGION", "Values": [ "us-east-1", "us-west-1" ], "MatchOptions": ["EQUALS"] }}, {"Dimensions": { "Key": "SERVICE", "Values": ["AWSLambda"], "MatchOptions": ["CONTAINS"] } } ]}, {"Not": {"Dimensions": { "Key": "USAGE_TYPE", "Values": ["DataTransfer"], "MatchOptions": ["CONTAINS"] }}} ] }``

         

        In the following **Contents**, you must specify exactly one of the following root operators.

        

      
  
    - **Not** *(dict) --* 

      Return results that don’t match the ``Expression`` that you specified.

      

    
    - **Dimensions** *(dict) --* 

      The specific dimension, values, and match type to filter objects with.

      

    
      - **Key** *(string) --* **[REQUIRED]** 

        The name of the dimension that you want to filter on.

        

      
      - **Values** *(list) --* **[REQUIRED]** 

        The metadata values you can specify to filter upon, so that the results all match at least one of the specified values.

        

      
        - *(string) --* 

        
    
      - **MatchOptions** *(list) --* **[REQUIRED]** 

        The match options that you can use to filter your results. You can specify only one of these values in the array.

        

      
        - *(string) --* 

        
    
    
  
  :type maxResults: integer
  :param maxResults: 

    The maximum number of results to return in the response. ``MaxResults`` means that there can be up to the specified number of values, but there might be fewer results based on your filters.

    

  
  :type nextToken: string
  :param nextToken: 

    The pagination token that indicates the next set of results to retrieve.

    

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

    
    ::

      {
          'freeTierUsages': [
              {
                  'service': 'string',
                  'operation': 'string',
                  'usageType': 'string',
                  'region': 'string',
                  'actualUsageAmount': 123.0,
                  'forecastedUsageAmount': 123.0,
                  'limit': 123.0,
                  'unit': 'string',
                  'description': 'string',
                  'freeTierType': 'string'
              },
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **freeTierUsages** *(list) --* 

        The list of Free Tier usage objects that meet your filter expression.

        
        

        - *(dict) --* 

          Consists of a Amazon Web Services Free Tier offer’s metadata and your data usage for the offer.

          
          

          - **service** *(string) --* 

            The name of the Amazon Web Services service providing the Free Tier offer. For example, this can be Amazon Elastic Compute Cloud.

            
          

          - **operation** *(string) --* 

            Describes ``usageType`` more granularly with the specific Amazon Web Services service API operation. For example, this can be the ``RunInstances`` API operation for Amazon Elastic Compute Cloud.

            
          

          - **usageType** *(string) --* 

            Describes the usage details of the offer. For example, this might be ``Global-BoxUsage:freetrial``.

            
          

          - **region** *(string) --* 

            Describes the Amazon Web Services Region for which this offer is applicable

            
          

          - **actualUsageAmount** *(float) --* 

            Describes the actual usage accrued month-to-day (MTD) that you've used so far.

            
          

          - **forecastedUsageAmount** *(float) --* 

            Describes the forecasted usage by the month that you're expected to use.

            
          

          - **limit** *(float) --* 

            Describes the maximum usage allowed in Free Tier.

            
          

          - **unit** *(string) --* 

            Describes the unit of the ``usageType``, such as ``Hrs``.

            
          

          - **description** *(string) --* 

            The description of the Free Tier offer.

            
          

          - **freeTierType** *(string) --* 

            Describes the type of the Free Tier offer. For example, the offer can be ``"12 Months Free"``, ``"Always Free"``, and ``"Free Trial"``.

            
      
    
      

      - **nextToken** *(string) --* 

        The pagination token that indicates the next set of results to retrieve.

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

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

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

  