:doc:`QConnect <../../qconnect>` / Paginator / ListSpans

*********
ListSpans
*********



.. py:class:: QConnect.Paginator.ListSpans

  ::

    
    paginator = client.get_paginator('list_spans')

  
  

  .. py:method:: paginate(**kwargs)

    Creates an iterator that will paginate through responses from :py:meth:`QConnect.Client.list_spans`.

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


    **Request Syntax**
    ::

      response_iterator = paginator.paginate(
          assistantId='string',
          sessionId='string',
          PaginationConfig={
              'MaxItems': 123,
              'PageSize': 123,
              'StartingToken': 'string'
          }
      )
      
    :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 PaginationConfig: dict
    :param PaginationConfig: 

      A dictionary that provides parameters to control pagination.

      

    
      - **MaxItems** *(integer) --* 

        The total number of items to return. If the total number of items available is more than the value specified in max-items then a ``NextToken`` will be provided in the output that you can use to resume pagination.

        

      
      - **PageSize** *(integer) --* 

        The size of each page.

        

      
      - **StartingToken** *(string) --* 

        A token to specify where to start paginating. This is the ``NextToken`` from a previous response.

        

      
    
    
    :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) --* 

          A token to resume pagination.

          
    