:doc:`SSM <../../ssm>` / Client / describe_sessions

*****************
describe_sessions
*****************



.. py:method:: SSM.Client.describe_sessions(**kwargs)

  

  Retrieves a list of all active sessions (both connected and disconnected) or terminated sessions from the past 30 days.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ssm-2014-11-06/DescribeSessions>`_  


  **Request Syntax**
  ::

    response = client.describe_sessions(
        State='Active'|'History',
        MaxResults=123,
        NextToken='string',
        Filters=[
            {
                'key': 'InvokedAfter'|'InvokedBefore'|'Target'|'Owner'|'Status'|'SessionId'|'AccessType',
                'value': 'string'
            },
        ]
    )
    
  :type State: string
  :param State: **[REQUIRED]** 

    The session status to retrieve a list of sessions for. For example, "Active".

    

  
  :type MaxResults: integer
  :param MaxResults: 

    The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

    

  
  :type NextToken: string
  :param NextToken: 

    The token for the next set of items to return. (You received this token from a previous call.)

    

  
  :type Filters: list
  :param Filters: 

    One or more filters to limit the type of sessions returned by the request.

    

  
    - *(dict) --* 

      Describes a filter for Session Manager information.

      

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

        The name of the filter.

        

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

        The filter value. Valid values for each filter key are as follows:

         

        
        * InvokedAfter: Specify a timestamp to limit your results. For example, specify 2024-08-29T00:00:00Z to see sessions that started August 29, 2024, and later.
         
        * InvokedBefore: Specify a timestamp to limit your results. For example, specify 2024-08-29T00:00:00Z to see sessions that started before August 29, 2024.
         
        * Target: Specify a managed node to which session connections have been made.
         
        * Owner: Specify an Amazon Web Services user to see a list of sessions started by that user.
         
        * Status: Specify a valid session status to see a list of all sessions with that status. Status values you can specify include: 

          
          * Connected
           
          * Connecting
           
          * Disconnected
           
          * Terminated
           
          * Terminating
           
          * Failed
          

        
         
        * SessionId: Specify a session ID to return details about the session.
        

        

      
    

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

    
    ::

      {
          'Sessions': [
              {
                  'SessionId': 'string',
                  'Target': 'string',
                  'Status': 'Connected'|'Connecting'|'Disconnected'|'Terminated'|'Terminating'|'Failed',
                  'StartDate': datetime(2015, 1, 1),
                  'EndDate': datetime(2015, 1, 1),
                  'DocumentName': 'string',
                  'Owner': 'string',
                  'Reason': 'string',
                  'Details': 'string',
                  'OutputUrl': {
                      'S3OutputUrl': 'string',
                      'CloudWatchOutputUrl': 'string'
                  },
                  'MaxSessionDuration': 'string',
                  'AccessType': 'Standard'|'JustInTime'
              },
          ],
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Sessions** *(list) --* 

        A list of sessions meeting the request parameters.

        
        

        - *(dict) --* 

          Information about a Session Manager connection to a managed node.

          
          

          - **SessionId** *(string) --* 

            The ID of the session.

            
          

          - **Target** *(string) --* 

            The managed node that the Session Manager session connected to.

            
          

          - **Status** *(string) --* 

            The status of the session. For example, "Connected" or "Terminated".

            
          

          - **StartDate** *(datetime) --* 

            The date and time, in ISO-8601 Extended format, when the session began.

            
          

          - **EndDate** *(datetime) --* 

            The date and time, in ISO-8601 Extended format, when the session was terminated.

            
          

          - **DocumentName** *(string) --* 

            The name of the Session Manager SSM document used to define the parameters and plugin settings for the session. For example, ``SSM-SessionManagerRunShell``.

            
          

          - **Owner** *(string) --* 

            The ID of the Amazon Web Services user that started the session.

            
          

          - **Reason** *(string) --* 

            The reason for connecting to the instance.

            
          

          - **Details** *(string) --* 

            Reserved for future use.

            
          

          - **OutputUrl** *(dict) --* 

            Reserved for future use.

            
            

            - **S3OutputUrl** *(string) --* 

              Reserved for future use.

              
            

            - **CloudWatchOutputUrl** *(string) --* 

              Reserved for future use.

              
        
          

          - **MaxSessionDuration** *(string) --* 

            The maximum duration of a session before it terminates.

            
          

          - **AccessType** *(string) --* 

            ``Standard`` access type is the default for Session Manager sessions. ``JustInTime`` is the access type for `Just-in-time node access <https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-just-in-time-node-access.html>`__.

            
      
    
      

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

        The token for the next set of items to return. (You received this token from a previous call.)

        
  
  **Exceptions**
  
  *   :py:class:`SSM.Client.exceptions.InternalServerError`

  
  *   :py:class:`SSM.Client.exceptions.InvalidFilterKey`

  
  *   :py:class:`SSM.Client.exceptions.InvalidNextToken`

  