:doc:`SSMContacts <../../ssm-contacts>` / Client / list_engagements

****************
list_engagements
****************



.. py:method:: SSMContacts.Client.list_engagements(**kwargs)

  

  Lists all engagements that have happened in an incident.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ssm-contacts-2021-05-03/ListEngagements>`_  


  **Request Syntax**
  ::

    response = client.list_engagements(
        NextToken='string',
        MaxResults=123,
        IncidentId='string',
        TimeRangeValue={
            'StartTime': datetime(2015, 1, 1),
            'EndTime': datetime(2015, 1, 1)
        }
    )
    
  :type NextToken: string
  :param NextToken: 

    The pagination token to continue to the next page of results.

    

  
  :type MaxResults: integer
  :param MaxResults: 

    The maximum number of engagements per page of results.

    

  
  :type IncidentId: string
  :param IncidentId: 

    The Amazon Resource Name (ARN) of the incident you're listing engagements for.

    

  
  :type TimeRangeValue: dict
  :param TimeRangeValue: 

    The time range to lists engagements for an incident.

    

  
    - **StartTime** *(datetime) --* 

      The start of the time range.

      

    
    - **EndTime** *(datetime) --* 

      The end of the time range.

      

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

    
    ::

      {
          'NextToken': 'string',
          'Engagements': [
              {
                  'EngagementArn': 'string',
                  'ContactArn': 'string',
                  'Sender': 'string',
                  'IncidentId': 'string',
                  'StartTime': datetime(2015, 1, 1),
                  'StopTime': datetime(2015, 1, 1)
              },
          ]
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

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

        The pagination token to continue to the next page of results.

        
      

      - **Engagements** *(list) --* 

        A list of each engagement that occurred during the specified time range of an incident.

        
        

        - *(dict) --* 

          Incident Manager reaching out to a contact or escalation plan to engage contact during an incident.

          
          

          - **EngagementArn** *(string) --* 

            The Amazon Resource Name (ARN) of the engagement.

            
          

          - **ContactArn** *(string) --* 

            The ARN of the escalation plan or contact that Incident Manager is engaging.

            
          

          - **Sender** *(string) --* 

            The user that started the engagement.

            
          

          - **IncidentId** *(string) --* 

            The ARN of the incident that's engaging the contact.

            
          

          - **StartTime** *(datetime) --* 

            The time that the engagement began.

            
          

          - **StopTime** *(datetime) --* 

            The time that the engagement ended.

            
      
    
  
  **Exceptions**
  
  *   :py:class:`SSMContacts.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`SSMContacts.Client.exceptions.InternalServerException`

  
  *   :py:class:`SSMContacts.Client.exceptions.ThrottlingException`

  
  *   :py:class:`SSMContacts.Client.exceptions.ValidationException`

  

  **Examples**

  The following list-engagements example lists engagements to escalation plans and contacts. You can also list engagements for a single incident.
  ::

    response = client.list_engagements(
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'Engagements': [
            {
                'ContactArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:contact/akuam',
                'EngagementArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:engagement/akuam/91792571-0b53-4821-9f73-d25d13d9e529',
                'Sender': 'cli',
                'StartTime': datetime(2021, 5, 18, 20, 37, 50, 1, 138, 0),
            },
            {
                'ContactArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:contact/akuam',
                'EngagementArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:engagement/akuam/78a29753-3674-4ac5-9f83-0468563567f0',
                'Sender': 'cli',
                'StartTime': datetime(2021, 5, 18, 18, 40, 26, 1, 138, 0),
            },
            {
                'ContactArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:contact/example_escalation',
                'EngagementArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:engagement/example_escalation/69e40ce1-8dbb-4d57-8962-5fbe7fc53356',
                'Sender': 'cli',
                'StartTime': datetime(2021, 5, 18, 18, 25, 41, 1, 138, 0),
            },
            {
                'ContactArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:contact/akuam',
                'EngagementArn': 'arn:aws:ssm-contacts:us-east-2:111122223333:engagement/akuam/607ced0e-e8fa-4ea7-8958-a237b8803f8f',
                'Sender': 'cli',
                'StartTime': datetime(2021, 5, 18, 18, 20, 58, 1, 138, 0),
            },
        ],
        'ResponseMetadata': {
            '...': '...',
        },
    }

  