:doc:`EC2 <../../ec2>` / Client / describe_scheduled_instances

****************************
describe_scheduled_instances
****************************



.. py:method:: EC2.Client.describe_scheduled_instances(**kwargs)

  

  Describes the specified Scheduled Instances or all your Scheduled Instances.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ec2-2016-11-15/DescribeScheduledInstances>`_  


  **Request Syntax**
  ::

    response = client.describe_scheduled_instances(
        DryRun=True|False,
        Filters=[
            {
                'Name': 'string',
                'Values': [
                    'string',
                ]
            },
        ],
        MaxResults=123,
        NextToken='string',
        ScheduledInstanceIds=[
            'string',
        ],
        SlotStartTimeRange={
            'EarliestTime': datetime(2015, 1, 1),
            'LatestTime': datetime(2015, 1, 1)
        }
    )
    
  :type DryRun: boolean
  :param DryRun: 

    Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is ``DryRunOperation``. Otherwise, it is ``UnauthorizedOperation``.

    

  
  :type Filters: list
  :param Filters: 

    The filters.

     

    
    * ``availability-zone`` - The Availability Zone (for example, ``us-west-2a``).
     
    * ``instance-type`` - The instance type (for example, ``c4.large``).
     
    * ``platform`` - The platform ( ``Linux/UNIX`` or ``Windows``).
    

    

  
    - *(dict) --* 

      A filter name and value pair that is used to return a more specific list of results from a describe operation. Filters can be used to match a set of resources by specific criteria, such as tags, attributes, or IDs.

       

      If you specify multiple filters, the filters are joined with an ``AND``, and the request returns only results that match all of the specified filters.

       

      For more information, see `List and filter using the CLI and API <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Filtering.html#Filtering_Resources_CLI>`__ in the *Amazon EC2 User Guide*.

      

    
      - **Name** *(string) --* 

        The name of the filter. Filter names are case-sensitive.

        

      
      - **Values** *(list) --* 

        The filter values. Filter values are case-sensitive. If you specify multiple values for a filter, the values are joined with an ``OR``, and the request returns all results that match any of the specified values.

        

      
        - *(string) --* 

        
    
    

  :type MaxResults: integer
  :param MaxResults: 

    The maximum number of results to return in a single call. This value can be between 5 and 300. The default value is 100. To retrieve the remaining results, make another call with the returned ``NextToken`` value.

    

  
  :type NextToken: string
  :param NextToken: 

    The token for the next set of results.

    

  
  :type ScheduledInstanceIds: list
  :param ScheduledInstanceIds: 

    The Scheduled Instance IDs.

    

  
    - *(string) --* 

    

  :type SlotStartTimeRange: dict
  :param SlotStartTimeRange: 

    The time period for the first schedule to start.

    

  
    - **EarliestTime** *(datetime) --* 

      The earliest date and time, in UTC, for the Scheduled Instance to start.

      

    
    - **LatestTime** *(datetime) --* 

      The latest date and time, in UTC, for the Scheduled Instance to start.

      

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

    
    ::

      {
          'NextToken': 'string',
          'ScheduledInstanceSet': [
              {
                  'AvailabilityZone': 'string',
                  'CreateDate': datetime(2015, 1, 1),
                  'HourlyPrice': 'string',
                  'InstanceCount': 123,
                  'InstanceType': 'string',
                  'NetworkPlatform': 'string',
                  'NextSlotStartTime': datetime(2015, 1, 1),
                  'Platform': 'string',
                  'PreviousSlotEndTime': datetime(2015, 1, 1),
                  'Recurrence': {
                      'Frequency': 'string',
                      'Interval': 123,
                      'OccurrenceDaySet': [
                          123,
                      ],
                      'OccurrenceRelativeToEnd': True|False,
                      'OccurrenceUnit': 'string'
                  },
                  'ScheduledInstanceId': 'string',
                  'SlotDurationInHours': 123,
                  'TermEndDate': datetime(2015, 1, 1),
                  'TermStartDate': datetime(2015, 1, 1),
                  'TotalScheduledInstanceHours': 123
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 

      Contains the output of DescribeScheduledInstances.

      
      

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

        The token required to retrieve the next set of results. This value is ``null`` when there are no more results to return.

        
      

      - **ScheduledInstanceSet** *(list) --* 

        Information about the Scheduled Instances.

        
        

        - *(dict) --* 

          Describes a Scheduled Instance.

          
          

          - **AvailabilityZone** *(string) --* 

            The Availability Zone.

            
          

          - **CreateDate** *(datetime) --* 

            The date when the Scheduled Instance was purchased.

            
          

          - **HourlyPrice** *(string) --* 

            The hourly price for a single instance.

            
          

          - **InstanceCount** *(integer) --* 

            The number of instances.

            
          

          - **InstanceType** *(string) --* 

            The instance type.

            
          

          - **NetworkPlatform** *(string) --* 

            The network platform.

            
          

          - **NextSlotStartTime** *(datetime) --* 

            The time for the next schedule to start.

            
          

          - **Platform** *(string) --* 

            The platform ( ``Linux/UNIX`` or ``Windows``).

            
          

          - **PreviousSlotEndTime** *(datetime) --* 

            The time that the previous schedule ended or will end.

            
          

          - **Recurrence** *(dict) --* 

            The schedule recurrence.

            
            

            - **Frequency** *(string) --* 

              The frequency ( ``Daily``, ``Weekly``, or ``Monthly``).

              
            

            - **Interval** *(integer) --* 

              The interval quantity. The interval unit depends on the value of ``frequency``. For example, every 2 weeks or every 2 months.

              
            

            - **OccurrenceDaySet** *(list) --* 

              The days. For a monthly schedule, this is one or more days of the month (1-31). For a weekly schedule, this is one or more days of the week (1-7, where 1 is Sunday).

              
              

              - *(integer) --* 
          
            

            - **OccurrenceRelativeToEnd** *(boolean) --* 

              Indicates whether the occurrence is relative to the end of the specified week or month.

              
            

            - **OccurrenceUnit** *(string) --* 

              The unit for ``occurrenceDaySet`` ( ``DayOfWeek`` or ``DayOfMonth``).

              
        
          

          - **ScheduledInstanceId** *(string) --* 

            The Scheduled Instance ID.

            
          

          - **SlotDurationInHours** *(integer) --* 

            The number of hours in the schedule.

            
          

          - **TermEndDate** *(datetime) --* 

            The end date for the Scheduled Instance.

            
          

          - **TermStartDate** *(datetime) --* 

            The start date for the Scheduled Instance.

            
          

          - **TotalScheduledInstanceHours** *(integer) --* 

            The total number of hours for a single instance for the entire term.

            
      
    
  

  **Examples**

  This example describes the specified Scheduled Instance.
  ::

    response = client.describe_scheduled_instances(
        ScheduledInstanceIds=[
            'sci-1234-1234-1234-1234-123456789012',
        ],
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'ScheduledInstanceSet': [
            {
                'AvailabilityZone': 'us-west-2b',
                'CreateDate': datetime(2016, 1, 25, 21, 43, 38, 0, 25, 0),
                'HourlyPrice': '0.095',
                'InstanceCount': 1,
                'InstanceType': 'c4.large',
                'NetworkPlatform': 'EC2-VPC',
                'NextSlotStartTime': datetime(2016, 1, 31, 9, 0, 0, 6, 31, 0),
                'Platform': 'Linux/UNIX',
                'Recurrence': {
                    'Frequency': 'Weekly',
                    'Interval': 1,
                    'OccurrenceDaySet': [
                        1,
                    ],
                    'OccurrenceRelativeToEnd': False,
                    'OccurrenceUnit': '',
                },
                'ScheduledInstanceId': 'sci-1234-1234-1234-1234-123456789012',
                'SlotDurationInHours': 32,
                'TermEndDate': datetime(2017, 1, 31, 9, 0, 0, 1, 31, 0),
                'TermStartDate': datetime(2016, 1, 31, 9, 0, 0, 6, 31, 0),
                'TotalScheduledInstanceHours': 1696,
            },
        ],
        'ResponseMetadata': {
            '...': '...',
        },
    }

  