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

****************************
purchase_scheduled_instances
****************************



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

  

  .. note::

    

    You can no longer purchase Scheduled Instances.

    

   

  Purchases the Scheduled Instances with the specified schedule.

   

  Scheduled Instances enable you to purchase Amazon EC2 compute capacity by the hour for a one-year term. Before you can purchase a Scheduled Instance, you must call  DescribeScheduledInstanceAvailability to check for available schedules and obtain a purchase token. After you purchase a Scheduled Instance, you must call  RunScheduledInstances during each scheduled time period.

   

  After you purchase a Scheduled Instance, you can't cancel, modify, or resell your purchase.

  

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


  **Request Syntax**
  ::

    response = client.purchase_scheduled_instances(
        ClientToken='string',
        DryRun=True|False,
        PurchaseRequests=[
            {
                'InstanceCount': 123,
                'PurchaseToken': 'string'
            },
        ]
    )
    
  :type ClientToken: string
  :param ClientToken: 

    Unique, case-sensitive identifier that ensures the idempotency of the request. For more information, see `Ensuring Idempotency <https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Run_Instance_Idempotency.html>`__.

    This field is autopopulated if not provided.

  
  :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 PurchaseRequests: list
  :param PurchaseRequests: **[REQUIRED]** 

    The purchase requests.

    

  
    - *(dict) --* 

      Describes a request to purchase Scheduled Instances.

      

    
      - **InstanceCount** *(integer) --* **[REQUIRED]** 

        The number of instances.

        

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

        The purchase token.

        

      
    

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

    
    ::

      {
          '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 PurchaseScheduledInstances.

      
      

      - **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 purchases a Scheduled Instance.
  ::

    response = client.purchase_scheduled_instances(
        PurchaseRequests=[
            {
                'InstanceCount': 1,
                'PurchaseToken': 'eyJ2IjoiMSIsInMiOjEsImMiOi...',
            },
        ],
    )
    
    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': {
            '...': '...',
        },
    }

  