:doc:`ECS <../../ecs>` / Client / list_container_instances

************************
list_container_instances
************************



.. py:method:: ECS.Client.list_container_instances(**kwargs)

  

  Returns a list of container instances in a specified cluster. You can filter the results of a ``ListContainerInstances`` operation with cluster query language statements inside the ``filter`` parameter. For more information, see `Cluster Query Language <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cluster-query-language.html>`__ in the *Amazon Elastic Container Service Developer Guide*.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ecs-2014-11-13/ListContainerInstances>`_  


  **Request Syntax**
  ::

    response = client.list_container_instances(
        cluster='string',
        filter='string',
        nextToken='string',
        maxResults=123,
        status='ACTIVE'|'DRAINING'|'REGISTERING'|'DEREGISTERING'|'REGISTRATION_FAILED'
    )
    
  :type cluster: string
  :param cluster: 

    The short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instances to list. If you do not specify a cluster, the default cluster is assumed.

    

  
  :type filter: string
  :param filter: 

    You can filter the results of a ``ListContainerInstances`` operation with cluster query language statements. For more information, see `Cluster Query Language <https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cluster-query-language.html>`__ in the *Amazon Elastic Container Service Developer Guide*.

    

  
  :type nextToken: string
  :param nextToken: 

    The ``nextToken`` value returned from a ``ListContainerInstances`` request indicating that more results are available to fulfill the request and further calls are needed. If ``maxResults`` was provided, it's possible the number of results to be fewer than ``maxResults``.

     

    .. note::

      

      This token should be treated as an opaque identifier that is only used to retrieve the next items in a list and not for other programmatic purposes.

      

    

  
  :type maxResults: integer
  :param maxResults: 

    The maximum number of container instance results that ``ListContainerInstances`` returned in paginated output. When this parameter is used, ``ListContainerInstances`` only returns ``maxResults`` results in a single page along with a ``nextToken`` response element. The remaining results of the initial request can be seen by sending another ``ListContainerInstances`` request with the returned ``nextToken`` value. This value can be between 1 and 100. If this parameter isn't used, then ``ListContainerInstances`` returns up to 100 results and a ``nextToken`` value if applicable.

    

  
  :type status: string
  :param status: 

    Filters the container instances by status. For example, if you specify the ``DRAINING`` status, the results include only container instances that have been set to ``DRAINING`` using `UpdateContainerInstancesState <https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateContainerInstancesState.html>`__. If you don't specify this parameter, the The default is to include container instances set to all states other than ``INACTIVE``.

    

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

    
    ::

      {
          'containerInstanceArns': [
              'string',
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **containerInstanceArns** *(list) --* 

        The list of container instances with full ARN entries for each container instance associated with the specified cluster.

        
        

        - *(string) --* 
    
      

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

        The ``nextToken`` value to include in a future ``ListContainerInstances`` request. When the results of a ``ListContainerInstances`` request exceed ``maxResults``, this value can be used to retrieve the next page of results. This value is ``null`` when there are no more results to return.

        
  
  **Exceptions**
  
  *   :py:class:`ECS.Client.exceptions.ServerException`

  
  *   :py:class:`ECS.Client.exceptions.ClientException`

  
  *   :py:class:`ECS.Client.exceptions.InvalidParameterException`

  
  *   :py:class:`ECS.Client.exceptions.ClusterNotFoundException`

  

  **Examples**

  This example lists all of your available container instances in the specified cluster in your default region.
  ::

    response = client.list_container_instances(
        cluster='default',
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'containerInstanceArns': [
            'arn:aws:ecs:us-east-1:<aws_account_id>:container-instance/f6bbb147-5370-4ace-8c73-c7181ded911f',
            'arn:aws:ecs:us-east-1:<aws_account_id>:container-instance/ffe3d344-77e2-476c-a4d0-bf560ad50acb',
        ],
        'ResponseMetadata': {
            '...': '...',
        },
    }

  