:doc:`BedrockAgentCore <../../bedrock-agentcore>` / Client / list_events

***********
list_events
***********



.. py:method:: BedrockAgentCore.Client.list_events(**kwargs)

  

  Lists events in an AgentCore Memory resource based on specified criteria. We recommend using pagination to ensure that the operation returns quickly and successfully.

   

  To use this operation, you must have the ``bedrock-agentcore:ListEvents`` permission.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/bedrock-agentcore-2024-02-28/ListEvents>`_  


  **Request Syntax**
  ::

    response = client.list_events(
        memoryId='string',
        sessionId='string',
        actorId='string',
        includePayloads=True|False,
        filter={
            'branch': {
                'name': 'string',
                'includeParentBranches': True|False
            },
            'eventMetadata': [
                {
                    'left': {
                        'metadataKey': 'string'
                    },
                    'operator': 'EQUALS_TO'|'EXISTS'|'NOT_EXISTS',
                    'right': {
                        'metadataValue': {
                            'stringValue': 'string'
                        }
                    }
                },
            ]
        },
        maxResults=123,
        nextToken='string'
    )
    
  :type memoryId: string
  :param memoryId: **[REQUIRED]** 

    The identifier of the AgentCore Memory resource for which to list events.

    

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

    The identifier of the session for which to list events.

    

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

    The identifier of the actor for which to list events.

    

  
  :type includePayloads: boolean
  :param includePayloads: 

    Specifies whether to include event payloads in the response. Set to true to include payloads, or false to exclude them.

    

  
  :type filter: dict
  :param filter: 

    Filter criteria to apply when listing events.

    

  
    - **branch** *(dict) --* 

      The branch filter criteria to apply when listing events.

      

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

        The name of the branch to filter by.

        

      
      - **includeParentBranches** *(boolean) --* 

        Specifies whether to include parent branches in the results. Set to true to include parent branches, or false to exclude them.

        

      
    
    - **eventMetadata** *(list) --* 

      Event metadata filter criteria to apply when retrieving events.

      

    
      - *(dict) --* 

        Filter expression for retrieving events based on metadata associated with an event.

        

      
        - **left** *(dict) --* **[REQUIRED]** 

          Left operand of the event metadata filter expression.

          .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``metadataKey``. 

        
          - **metadataKey** *(string) --* 

            Key associated with the metadata in an event.

            

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

          Operator applied to the event metadata filter expression.

          

        
        - **right** *(dict) --* 

          Right operand of the event metadata filter expression.

          .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``metadataValue``. 

        
          - **metadataValue** *(dict) --* 

            Value associated with the key in ``eventMetadata``.

            .. note::    This is a Tagged Union structure. Only one of the     following top level keys can be set: ``stringValue``. 

          
            - **stringValue** *(string) --* 

              Value associated with the ``eventMetadata`` key.

              

            
          
        
      
  
  
  :type maxResults: integer
  :param maxResults: 

    The maximum number of results to return in a single call. The default value is 20.

    

  
  :type nextToken: string
  :param nextToken: 

    The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

    

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

    
    ::

      {
          'events': [
              {
                  'memoryId': 'string',
                  'actorId': 'string',
                  'sessionId': 'string',
                  'eventId': 'string',
                  'eventTimestamp': datetime(2015, 1, 1),
                  'payload': [
                      {
                          'conversational': {
                              'content': {
                                  'text': 'string'
                              },
                              'role': 'ASSISTANT'|'USER'|'TOOL'|'OTHER'
                          },
                          'blob': {...}|[...]|123|123.4|'string'|True|None
                      },
                  ],
                  'branch': {
                      'rootEventId': 'string',
                      'name': 'string'
                  },
                  'metadata': {
                      'string': {
                          'stringValue': 'string'
                      }
                  }
              },
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **events** *(list) --* 

        The list of events that match the specified criteria.

        
        

        - *(dict) --* 

          Contains information about an event in an AgentCore Memory resource.

          
          

          - **memoryId** *(string) --* 

            The identifier of the AgentCore Memory resource containing the event.

            
          

          - **actorId** *(string) --* 

            The identifier of the actor associated with the event.

            
          

          - **sessionId** *(string) --* 

            The identifier of the session containing the event.

            
          

          - **eventId** *(string) --* 

            The unique identifier of the event.

            
          

          - **eventTimestamp** *(datetime) --* 

            The timestamp when the event occurred.

            
          

          - **payload** *(list) --* 

            The content payload of the event.

            
            

            - *(dict) --* 

              Contains the payload content for an event.

              .. note::    This is a Tagged Union structure. Only one of the     following top level keys will be set: ``conversational``, ``blob``.     If a client receives an unknown member it will     set ``SDK_UNKNOWN_MEMBER`` as the top level key,     which maps to the name or tag of the unknown     member. The structure of ``SDK_UNKNOWN_MEMBER`` is     as follows::

                            'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}


            
              

              - **conversational** *(dict) --* 

                The conversational content of the payload.

                
                

                - **content** *(dict) --* 

                  The content of the conversation message.

                  .. note::    This is a Tagged Union structure. Only one of the     following top level keys will be set: ``text``.     If a client receives an unknown member it will     set ``SDK_UNKNOWN_MEMBER`` as the top level key,     which maps to the name or tag of the unknown     member. The structure of ``SDK_UNKNOWN_MEMBER`` is     as follows::

                                    'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}


                
                  

                  - **text** *(string) --* 

                    The text content of the memory item.

                    
              
                

                - **role** *(string) --* 

                  The role of the participant in the conversation (for example, "user" or "assistant").

                  
            
              

              - **blob** (:ref:`document<document>`) -- 

                The binary content of the payload.

                
          
        
          

          - **branch** *(dict) --* 

            The branch information for the event.

            
            

            - **rootEventId** *(string) --* 

              The identifier of the root event for this branch.

              
            

            - **name** *(string) --* 

              The name of the branch.

              
        
          

          - **metadata** *(dict) --* 

            Metadata associated with an event.

            
            

            - *(string) --* 
              

              - *(dict) --* 

                Value associated with the ``eventMetadata`` key.

                .. note::    This is a Tagged Union structure. Only one of the     following top level keys will be set: ``stringValue``.     If a client receives an unknown member it will     set ``SDK_UNKNOWN_MEMBER`` as the top level key,     which maps to the name or tag of the unknown     member. The structure of ``SDK_UNKNOWN_MEMBER`` is     as follows::

                                'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}


              
                

                - **stringValue** *(string) --* 

                  Value associated with the ``eventMetadata`` key.

                  
            
        
      
      
    
      

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

        The token to use in a subsequent request to get the next set of results. This value is null when there are no more results to return.

        
  
  **Exceptions**
  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ServiceQuotaExceededException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ThrottledException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ServiceException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.AccessDeniedException`

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

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.InvalidInputException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ResourceNotFoundException`

  