:doc:`ServiceDiscovery <../../servicediscovery>` / Client / get_instances_health_status

***************************
get_instances_health_status
***************************



.. py:method:: ServiceDiscovery.Client.get_instances_health_status(**kwargs)

  

  Gets the current health status ( ``Healthy``, ``Unhealthy``, or ``Unknown``) of one or more instances that are associated with a specified service.

   

  .. note::

    

    There's a brief delay between when you register an instance and when the health status for the instance is available.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/servicediscovery-2017-03-14/GetInstancesHealthStatus>`_  


  **Request Syntax**
  ::

    response = client.get_instances_health_status(
        ServiceId='string',
        Instances=[
            'string',
        ],
        MaxResults=123,
        NextToken='string'
    )
    
  :type ServiceId: string
  :param ServiceId: **[REQUIRED]** 

    The ID or Amazon Resource Name (ARN) of the service that the instance is associated with. For services created in a shared namespace, specify the service ARN. For more information about shared namespaces, see `Cross-account Cloud Map namespace sharing <https://docs.aws.amazon.com/cloud-map/latest/dg/sharing-namespaces.html>`__ in the *Cloud Map Developer Guide*.

    

  
  :type Instances: list
  :param Instances: 

    An array that contains the IDs of all the instances that you want to get the health status for.

     

    If you omit ``Instances``, Cloud Map returns the health status for all the instances that are associated with the specified service.

     

    .. note::

      

      To get the IDs for the instances that you've registered by using a specified service, submit a `ListInstances <https://docs.aws.amazon.com/cloud-map/latest/api/API_ListInstances.html>`__ request.

      

    

  
    - *(string) --* 

    

  :type MaxResults: integer
  :param MaxResults: 

    The maximum number of instances that you want Cloud Map to return in the response to a ``GetInstancesHealthStatus`` request. If you don't specify a value for ``MaxResults``, Cloud Map returns up to 100 instances.

    

  
  :type NextToken: string
  :param NextToken: 

    For the first ``GetInstancesHealthStatus`` request, omit this value.

     

    If more than ``MaxResults`` instances match the specified criteria, you can submit another ``GetInstancesHealthStatus`` request to get the next group of results. Specify the value of ``NextToken`` from the previous response in the next request.

    

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

    
    ::

      {
          'Status': {
              'string': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN'
          },
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Status** *(dict) --* 

        A complex type that contains the IDs and the health status of the instances that you specified in the ``GetInstancesHealthStatus`` request.

        
        

        - *(string) --* 
          

          - *(string) --* 
    
  
      

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

        If more than ``MaxResults`` instances match the specified criteria, you can submit another ``GetInstancesHealthStatus`` request to get the next group of results. Specify the value of ``NextToken`` from the previous response in the next request.

        
  
  **Exceptions**
  
  *   :py:class:`ServiceDiscovery.Client.exceptions.InstanceNotFound`

  
  *   :py:class:`ServiceDiscovery.Client.exceptions.InvalidInput`

  
  *   :py:class:`ServiceDiscovery.Client.exceptions.ServiceNotFound`

  

  **Examples**

  This example gets the current health status of one or more instances that are associate with a specified service.
  ::

    response = client.get_instances_health_status(
        ServiceId='srv-e4anhexample0004',
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'Status': {
            'i-abcd1234': 'HEALTHY',
            'i-abcd1235': 'UNHEALTHY',
        },
        'ResponseMetadata': {
            '...': '...',
        },
    }

  