:doc:`AutoScaling <../../autoscaling>` / Client / launch_instances

****************
launch_instances
****************



.. py:method:: AutoScaling.Client.launch_instances(**kwargs)

  

  Launches a specified number of instances in an Auto Scaling group. Returns instance IDs and other details if launch is successful or error details if launch is unsuccessful.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/autoscaling-2011-01-01/LaunchInstances>`_  


  **Request Syntax**
  ::

    response = client.launch_instances(
        AutoScalingGroupName='string',
        RequestedCapacity=123,
        ClientToken='string',
        AvailabilityZones=[
            'string',
        ],
        AvailabilityZoneIds=[
            'string',
        ],
        SubnetIds=[
            'string',
        ],
        RetryStrategy='retry-with-group-configuration'|'none'
    )
    
  :type AutoScalingGroupName: string
  :param AutoScalingGroupName: **[REQUIRED]** 

    The name of the Auto Scaling group to launch instances into.

    

  
  :type RequestedCapacity: integer
  :param RequestedCapacity: **[REQUIRED]** 

    The number of instances to launch. Although this value can exceed 100 for instance weights, the actual instance count is limited to 100 instances per launch.

    

  
  :type ClientToken: string
  :param ClientToken: **[REQUIRED]** 

    A unique, case-sensitive identifier to ensure idempotency of the request.

    This field is autopopulated if not provided.

  
  :type AvailabilityZones: list
  :param AvailabilityZones: 

    The Availability Zones for the instance launch. Must match or be included in the Auto Scaling group's Availability Zone configuration. Either ``AvailabilityZones`` or ``SubnetIds`` must be specified for groups with multiple Availability Zone configurations.

    

  
    - *(string) --* 

    

  :type AvailabilityZoneIds: list
  :param AvailabilityZoneIds: 

    A list of Availability Zone IDs where instances should be launched. Must match or be included in the group's AZ configuration. You cannot specify both AvailabilityZones and AvailabilityZoneIds. Required for multi-AZ groups, optional for single-AZ groups.

    

  
    - *(string) --* 

    

  :type SubnetIds: list
  :param SubnetIds: 

    The subnet IDs for the instance launch. Either ``AvailabilityZones`` or ``SubnetIds`` must be specified. If both are specified, the subnets must reside in the specified Availability Zones.

    

  
    - *(string) --* 

    

  :type RetryStrategy: string
  :param RetryStrategy: 

    Specifies whether to retry asynchronously if the synchronous launch fails. Valid values are NONE (default, no async retry) and RETRY_WITH_GROUP_CONFIGURATION (increase desired capacity and retry with group configuration).

    

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

    
    ::

      {
          'AutoScalingGroupName': 'string',
          'ClientToken': 'string',
          'Instances': [
              {
                  'InstanceType': 'string',
                  'MarketType': 'string',
                  'SubnetId': 'string',
                  'AvailabilityZone': 'string',
                  'AvailabilityZoneId': 'string',
                  'InstanceIds': [
                      'string',
                  ]
              },
          ],
          'Errors': [
              {
                  'InstanceType': 'string',
                  'MarketType': 'string',
                  'SubnetId': 'string',
                  'AvailabilityZone': 'string',
                  'AvailabilityZoneId': 'string',
                  'ErrorCode': 'string',
                  'ErrorMessage': 'string'
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **AutoScalingGroupName** *(string) --* 

        The name of the Auto Scaling group where the instances were launched.

        
      

      - **ClientToken** *(string) --* 

        The idempotency token used for the request, either customer-specified or auto-generated.

        
      

      - **Instances** *(list) --* 

        A list of successfully launched instances including details such as instance type, Availability Zone, subnet, lifecycle state, and instance IDs.

        
        

        - *(dict) --* 

          Contains details about a collection of instances launched in the Auto Scaling group.

          
          

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

            The instance type of the launched instances.

            
          

          - **MarketType** *(string) --* 

            The market type for the instances (On-Demand or Spot).

            
          

          - **SubnetId** *(string) --* 

            The ID of the subnet where the instances were launched.

            
          

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

            The Availability Zone where the instances were launched.

            
          

          - **AvailabilityZoneId** *(string) --* 

            The Availability Zone ID where the instances in this collection were launched.

            
          

          - **InstanceIds** *(list) --* 

            A list of instance IDs for the successfully launched instances.

            
            

            - *(string) --* 
        
      
    
      

      - **Errors** *(list) --* 

        A list of errors encountered during the launch attempt including details about failed instance launches with their corresponding error codes and messages.

        
        

        - *(dict) --* 

          Contains details about errors encountered during instance launch attempts.

          
          

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

            The instance type that failed to launch.

            
          

          - **MarketType** *(string) --* 

            The market type (On-Demand or Spot) that encountered the launch error.

            
          

          - **SubnetId** *(string) --* 

            The subnet ID where the instance launch was attempted.

            
          

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

            The Availability Zone where the instance launch was attempted.

            
          

          - **AvailabilityZoneId** *(string) --* 

            The Availability Zone ID where the launch error occurred.

            
          

          - **ErrorCode** *(string) --* 

            The error code representing the type of error encountered (e.g., InsufficientInstanceCapacity).

            
          

          - **ErrorMessage** *(string) --* 

            A descriptive message providing details about the error encountered during the launch attempt.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`AutoScaling.Client.exceptions.ResourceContentionFault`

  
  *   :py:class:`AutoScaling.Client.exceptions.IdempotentParameterMismatchError`

  