QConnect / Paginator / ListSpans

ListSpans¶

class QConnect.Paginator.ListSpans¶

paginator = client.get_paginator('list_spans')

paginate(**kwargs)¶

Creates an iterator that will paginate through responses from QConnect.Client.list_spans().

Request Syntax

response_iterator = paginator.paginate(
    assistantId='string',
    sessionId='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)

Parameters:

assistantId (string) –
[REQUIRED]

UUID or ARN of the Connect AI Assistant resource
sessionId (string) –
[REQUIRED]

UUID or ARN of the Connect AI Session resource
PaginationConfig (dict) –
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.

Return type:

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 (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 (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 (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.