:doc:`QConnect <../../qconnect>` / Client / list_spans

**********
list_spans
**********



.. py:method:: QConnect.Client.list_spans(**kwargs)

  

  Retrieves AI agent execution traces for a session, providing granular visibility into agent orchestration flows, LLM interactions, and tool invocations.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/qconnect-2020-10-19/ListSpans>`_  


  **Request Syntax**
  ::

    response = client.list_spans(
        assistantId='string',
        sessionId='string',
        nextToken='string',
        maxResults=123
    )
    
  :type assistantId: string
  :param assistantId: **[REQUIRED]** 

    UUID or ARN of the Connect AI Assistant resource

    

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

    UUID or ARN of the Connect AI Session resource

    

  
  :type nextToken: string
  :param nextToken: 

    Pagination token for retrieving the next page of results

    

  
  :type maxResults: integer
  :param maxResults: 

    Maximum number of spans to return per page

    

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

    
    ::

      {
          'spans': [
              {
                  'spanId': 'string',
                  'assistantId': 'string',
                  'sessionId': 'string',
                  'parentSpanId': 'string',
                  'spanName': 'string',
                  'spanType': 'CLIENT'|'SERVER'|'INTERNAL',
                  'startTimestamp': datetime(2015, 1, 1),
                  'endTimestamp': datetime(2015, 1, 1),
                  'status': 'OK'|'ERROR'|'TIMEOUT',
                  'requestId': 'string',
                  'attributes': {
                      'operationName': 'string',
                      'providerName': 'string',
                      'errorType': 'string',
                      'agentId': 'string',
                      'instanceArn': 'string',
                      'contactId': 'string',
                      'initialContactId': 'string',
                      'sessionName': 'string',
                      'aiAgentArn': 'string',
                      'aiAgentType': 'MANUAL_SEARCH'|'ANSWER_RECOMMENDATION'|'SELF_SERVICE'|'EMAIL_RESPONSE'|'EMAIL_OVERVIEW'|'EMAIL_GENERATIVE_ANSWER'|'ORCHESTRATION'|'NOTE_TAKING'|'CASE_SUMMARIZATION',
                      'aiAgentName': 'string',
                      'aiAgentId': 'string',
                      'aiAgentVersion': 123,
                      'aiAgentInvoker': 'string',
                      'aiAgentOrchestratorUseCase': 'string',
                      'requestModel': 'string',
                      'requestMaxTokens': 123,
                      'temperature': ...,
                      'topP': ...,
                      'responseModel': 'string',
                      'responseFinishReasons': [
                          'string',
                      ],
                      'usageInputTokens': 123,
                      'usageOutputTokens': 123,
                      'usageTotalTokens': 123,
                      'cacheReadInputTokens': 123,
                      'cacheWriteInputTokens': 123,
                      'inputMessages': [
                          {
                              'messageId': 'string',
                              'participant': 'CUSTOMER'|'AGENT'|'BOT',
                              'timestamp': datetime(2015, 1, 1),
                              'values': [
                                  {
                                      'text': {
                                          'value': 'string',
                                          'citations': [
                                              {
                                                  'contentId': 'string',
                                                  'title': 'string',
                                                  'knowledgeBaseId': 'string',
                                                  'knowledgeBaseArn': 'string'
                                              },
                                          ],
                                          'aiGuardrailAssessment': {
                                              'blocked': True|False
                                          }
                                      },
                                      'toolUse': {
                                          'toolUseId': 'string',
                                          'name': 'string',
                                          'arguments': {...}|[...]|123|123.4|'string'|True|None
                                      },
                                      'toolResult': {
                                          'toolUseId': 'string',
                                          'values': {'... recursive ...'},
                                          'error': 'string'
                                      }
                                  },
                              ]
                          },
                      ],
                      'outputMessages': [
                          {
                              'messageId': 'string',
                              'participant': 'CUSTOMER'|'AGENT'|'BOT',
                              'timestamp': datetime(2015, 1, 1),
                              'values': [
                                  {
                                      'text': {
                                          'value': 'string',
                                          'citations': [
                                              {
                                                  'contentId': 'string',
                                                  'title': 'string',
                                                  'knowledgeBaseId': 'string',
                                                  'knowledgeBaseArn': 'string'
                                              },
                                          ],
                                          'aiGuardrailAssessment': {
                                              'blocked': True|False
                                          }
                                      },
                                      'toolUse': {
                                          'toolUseId': 'string',
                                          'name': 'string',
                                          'arguments': {...}|[...]|123|123.4|'string'|True|None
                                      },
                                      'toolResult': {
                                          'toolUseId': 'string',
                                          'values': {'... recursive ...'},
                                          'error': 'string'
                                      }
                                  },
                              ]
                          },
                      ],
                      'systemInstructions': [
                          {
                              'text': {
                                  'value': 'string',
                                  'citations': [
                                      {
                                          'contentId': 'string',
                                          'title': 'string',
                                          'knowledgeBaseId': 'string',
                                          'knowledgeBaseArn': 'string'
                                      },
                                  ],
                                  'aiGuardrailAssessment': {
                                      'blocked': True|False
                                  }
                              },
                              'toolUse': {
                                  'toolUseId': 'string',
                                  'name': 'string',
                                  'arguments': {...}|[...]|123|123.4|'string'|True|None
                              },
                              'toolResult': {
                                  'toolUseId': 'string',
                                  'values': {'... recursive ...'},
                                  'error': 'string'
                              }
                          },
                      ],
                      'promptArn': 'string',
                      'promptId': 'string',
                      'promptType': 'ANSWER_GENERATION'|'INTENT_LABELING_GENERATION'|'QUERY_REFORMULATION'|'SELF_SERVICE_PRE_PROCESSING'|'SELF_SERVICE_ANSWER_GENERATION'|'EMAIL_RESPONSE'|'EMAIL_OVERVIEW'|'EMAIL_GENERATIVE_ANSWER'|'EMAIL_QUERY_REFORMULATION'|'ORCHESTRATION'|'NOTE_TAKING'|'CASE_SUMMARIZATION',
                      'promptName': 'string',
                      'promptVersion': 123
                  }
              },
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **spans** *(list) --* 

        Array of span objects for the session

        
        

        - *(dict) --* 

          A span represents a unit of work during AI agent execution, capturing timing, status, and contextual attributes.

          
          

          - **spanId** *(string) --* 

            Unique span identifier

            
          

          - **assistantId** *(string) --* 

            UUID of the Connect AI Assistant resource

            
          

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

            UUID of the Connect AI Session resource

            
          

          - **parentSpanId** *(string) --* 

            Parent span identifier for hierarchy. Null for root spans.

            
          

          - **spanName** *(string) --* 

            Service-defined operation name

            
          

          - **spanType** *(string) --* 

            Operation relationship type

            
          

          - **startTimestamp** *(datetime) --* 

            Operation start time in milliseconds since epoch

            
          

          - **endTimestamp** *(datetime) --* 

            Operation end time in milliseconds since epoch

            
          

          - **status** *(string) --* 

            Span completion status

            
          

          - **requestId** *(string) --* 

            The service request ID that initiated the operation

            
          

          - **attributes** *(dict) --* 

            Span-specific contextual attributes

            
            

            - **operationName** *(string) --* 

              Action being performed

              
            

            - **providerName** *(string) --* 

              Model provider identifier (e.g., aws.bedrock)

              
            

            - **errorType** *(string) --* 

              Error classification if span failed (e.g., throttle, timeout)

              
            

            - **agentId** *(string) --* 

              Amazon Connect agent ID

              
            

            - **instanceArn** *(string) --* 

              Amazon Connect instance ARN

              
            

            - **contactId** *(string) --* 

              Amazon Connect contact identifier

              
            

            - **initialContactId** *(string) --* 

              Amazon Connect contact identifier

              
            

            - **sessionName** *(string) --* 

              Session name

              
            

            - **aiAgentArn** *(string) --* 

              AI agent ARN

              
            

            - **aiAgentType** *(string) --* 

              AI agent type

              
            

            - **aiAgentName** *(string) --* 

              AI agent name

              
            

            - **aiAgentId** *(string) --* 

              AI agent identifier

              
            

            - **aiAgentVersion** *(integer) --* 

              AI agent version number

              
            

            - **aiAgentInvoker** *(string) --* 

              Entity that invoked the AI agent

              
            

            - **aiAgentOrchestratorUseCase** *(string) --* 

              AI agent orchestrator use case

              
            

            - **requestModel** *(string) --* 

              LLM model ID for request (e.g., anthropic.claude-3-sonnet)

              
            

            - **requestMaxTokens** *(integer) --* 

              Maximum tokens configured for generation

              
            

            - **temperature** *(float) --* 

              Sampling temperature for generation

              
            

            - **topP** *(float) --* 

              Top-p sampling parameter for generation

              
            

            - **responseModel** *(string) --* 

              Actual model used for response (usually matches requestModel)

              
            

            - **responseFinishReasons** *(list) --* 

              Generation termination reasons (e.g., stop, max_tokens)

              
              

              - *(string) --* 
          
            

            - **usageInputTokens** *(integer) --* 

              Number of input tokens in prompt

              
            

            - **usageOutputTokens** *(integer) --* 

              Number of output tokens in response

              
            

            - **usageTotalTokens** *(integer) --* 

              Total tokens consumed (input + output)

              
            

            - **cacheReadInputTokens** *(integer) --* 

              Number of input tokens that were retrieved from cache

              
            

            - **cacheWriteInputTokens** *(integer) --* 

              Number of input tokens that were written to cache in this request

              
            

            - **inputMessages** *(list) --* 

              Input message collection sent to LLM

              
              

              - *(dict) --* 

                A message in the conversation history with participant role and content values

                
                

                - **messageId** *(string) --* 

                  Unique message identifier

                  
                

                - **participant** *(string) --* 

                  Message source role

                  
                

                - **timestamp** *(datetime) --* 

                  Message timestamp

                  
                

                - **values** *(list) --* 

                  Message content values (text, tool use, tool result)

                  
                  

                  - *(dict) --* 

                    Message content value - can be text, tool invocation, or tool result

                    .. note::    This is a Tagged Union structure. Only one of the     following top level keys will be set: ``text``, ``toolUse``, ``toolResult``.     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** *(dict) --* 

                      Text message content

                      
                      

                      - **value** *(string) --* 

                        String content of the message text

                        
                      

                      - **citations** *(list) --* 

                        The citations associated with the span text.

                        
                        

                        - *(dict) --* 

                          A citation that spans a specific range of text.

                          
                          

                          - **contentId** *(string) --* 

                            The identifier of the content being cited in the span.

                            
                          

                          - **title** *(string) --* 

                            The title of the content being cited in the span.

                            
                          

                          - **knowledgeBaseId** *(string) --* 

                            The identifier of the knowledge base containing the cited content.

                            
                          

                          - **knowledgeBaseArn** *(string) --* 

                            The Amazon Resource Name (ARN) of the knowledge base containing the cited content.

                            
                      
                    
                      

                      - **aiGuardrailAssessment** *(dict) --* 

                        The AI Guardrail assessment for the span text.

                        
                        

                        - **blocked** *(boolean) --* 

                          Indicates whether the AI Guardrail blocked the content.

                          
                    
                  
                    

                    - **toolUse** *(dict) --* 

                      Tool invocation message content

                      
                      

                      - **toolUseId** *(string) --* 

                        Unique ID for this tool invocation

                        
                      

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

                        The tool name

                        
                      

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

                        The tool input arguments

                        
                  
                    

                    - **toolResult** *(dict) --* 

                      Tool result message content

                      
                      

                      - **toolUseId** *(string) --* 

                        Relates this result back to the tool invocation

                        
                      

                      - **values** *(list) --* 

                        The tool results

                        
                      

                      - **error** *(string) --* 

                        The tool invocation error if failed

                        
                  
                
              
            
          
            

            - **outputMessages** *(list) --* 

              Output message collection received from LLM

              
              

              - *(dict) --* 

                A message in the conversation history with participant role and content values

                
                

                - **messageId** *(string) --* 

                  Unique message identifier

                  
                

                - **participant** *(string) --* 

                  Message source role

                  
                

                - **timestamp** *(datetime) --* 

                  Message timestamp

                  
                

                - **values** *(list) --* 

                  Message content values (text, tool use, tool result)

                  
                  

                  - *(dict) --* 

                    Message content value - can be text, tool invocation, or tool result

                    .. note::    This is a Tagged Union structure. Only one of the     following top level keys will be set: ``text``, ``toolUse``, ``toolResult``.     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** *(dict) --* 

                      Text message content

                      
                      

                      - **value** *(string) --* 

                        String content of the message text

                        
                      

                      - **citations** *(list) --* 

                        The citations associated with the span text.

                        
                        

                        - *(dict) --* 

                          A citation that spans a specific range of text.

                          
                          

                          - **contentId** *(string) --* 

                            The identifier of the content being cited in the span.

                            
                          

                          - **title** *(string) --* 

                            The title of the content being cited in the span.

                            
                          

                          - **knowledgeBaseId** *(string) --* 

                            The identifier of the knowledge base containing the cited content.

                            
                          

                          - **knowledgeBaseArn** *(string) --* 

                            The Amazon Resource Name (ARN) of the knowledge base containing the cited content.

                            
                      
                    
                      

                      - **aiGuardrailAssessment** *(dict) --* 

                        The AI Guardrail assessment for the span text.

                        
                        

                        - **blocked** *(boolean) --* 

                          Indicates whether the AI Guardrail blocked the content.

                          
                    
                  
                    

                    - **toolUse** *(dict) --* 

                      Tool invocation message content

                      
                      

                      - **toolUseId** *(string) --* 

                        Unique ID for this tool invocation

                        
                      

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

                        The tool name

                        
                      

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

                        The tool input arguments

                        
                  
                    

                    - **toolResult** *(dict) --* 

                      Tool result message content

                      
                      

                      - **toolUseId** *(string) --* 

                        Relates this result back to the tool invocation

                        
                      

                      - **values** *(list) --* 

                        The tool results

                        
                      

                      - **error** *(string) --* 

                        The tool invocation error if failed

                        
                  
                
              
            
          
            

            - **systemInstructions** *(list) --* 

              System prompt instructions

              
              

              - *(dict) --* 

                Message content value - can be text, tool invocation, or tool result

                .. note::    This is a Tagged Union structure. Only one of the     following top level keys will be set: ``text``, ``toolUse``, ``toolResult``.     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** *(dict) --* 

                  Text message content

                  
                  

                  - **value** *(string) --* 

                    String content of the message text

                    
                  

                  - **citations** *(list) --* 

                    The citations associated with the span text.

                    
                    

                    - *(dict) --* 

                      A citation that spans a specific range of text.

                      
                      

                      - **contentId** *(string) --* 

                        The identifier of the content being cited in the span.

                        
                      

                      - **title** *(string) --* 

                        The title of the content being cited in the span.

                        
                      

                      - **knowledgeBaseId** *(string) --* 

                        The identifier of the knowledge base containing the cited content.

                        
                      

                      - **knowledgeBaseArn** *(string) --* 

                        The Amazon Resource Name (ARN) of the knowledge base containing the cited content.

                        
                  
                
                  

                  - **aiGuardrailAssessment** *(dict) --* 

                    The AI Guardrail assessment for the span text.

                    
                    

                    - **blocked** *(boolean) --* 

                      Indicates whether the AI Guardrail blocked the content.

                      
                
              
                

                - **toolUse** *(dict) --* 

                  Tool invocation message content

                  
                  

                  - **toolUseId** *(string) --* 

                    Unique ID for this tool invocation

                    
                  

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

                    The tool name

                    
                  

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

                    The tool input arguments

                    
              
                

                - **toolResult** *(dict) --* 

                  Tool result message content

                  
                  

                  - **toolUseId** *(string) --* 

                    Relates this result back to the tool invocation

                    
                  

                  - **values** *(list) --* 

                    The tool results

                    
                  

                  - **error** *(string) --* 

                    The tool invocation error if failed

                    
              
            
          
            

            - **promptArn** *(string) --* 

              AI prompt ARN

              
            

            - **promptId** *(string) --* 

              AI prompt identifier

              
            

            - **promptType** *(string) --* 

              AI prompt type

              
            

            - **promptName** *(string) --* 

              AI prompt name

              
            

            - **promptVersion** *(integer) --* 

              AI prompt version number

              
        
      
    
      

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

        Pagination token for retrieving additional results

        
  
  **Exceptions**
  
  *   :py:class:`QConnect.Client.exceptions.ValidationException`

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

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

  