> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesimple.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Interactions

> List all interactions (calls and text conversations) with pagination and filtering

By default, this endpoint returns native calls and conversations only. Pass `include_external_channels=true` to include external-channel sessions, grouped one per session, alongside native interactions. The `type` field identifies whether each interaction is a `call`, `conversation`, `email`, `sms`, or `external_channel`.


## OpenAPI

````yaml GET /interactions
openapi: 3.1.0
info:
  title: Public API v1
  description: >-
    Public API v1 requiring API keys.


    **Timestamps:** All datetime fields in API responses are returned in UTC
    using ISO 8601 format (e.g., `2024-01-15T14:30:00Z`). When filtering by date
    parameters, provide timestamps in ISO 8601 format.
  version: 0.1.0
servers:
  - url: https://api.prod.usesimple.ai/api/v1
    description: Production API Server
security: []
paths:
  /interactions:
    get:
      tags:
        - Interactions
      summary: List Interactions
      description: >-
        List all interactions (calls, text conversations, and external-channel
        interactions) associated with the API key's account.

        Includes pagination support and filtering by status, modality,
        transferred state, external-channel inclusion, and creation date.

        Date filters accept ISO 8601 format (e.g., 2024-01-15T09:30:00Z).
      operationId: list_interactions_interactions_get
      parameters:
        - name: page
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            default: 1
            title: Page
        - name: page_size
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            default: 20
            title: Page Size
        - name: status
          in: query
          required: false
          schema:
            type: string
            title: Status
          description: >-
            Filter by interaction status. Multiple values can be provided
            separated by commas.
        - name: modality
          in: query
          required: false
          schema:
            type: string
            enum:
              - voice
              - text
            title: Modality
          description: Filter by interaction modality (voice or text)
        - name: agent_id
          in: query
          required: false
          schema:
            type: string
            title: Agent ID
          description: >-
            Filter by agent group UUID. Multiple values can be provided
            separated by commas. Returns interactions from all versions of the
            specified agent(s).
        - name: agent_version_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
            title: Agent Version ID
          description: >-
            Filter by specific agent version UUID. Returns interactions from
            only the specified agent version.
        - name: transferred
          in: query
          required: false
          schema:
            type: boolean
            title: Transferred
          description: Filter by whether the interaction was transferred
        - name: include_external_channels
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include External Channels
          description: >-
            External-channel calls (uploaded or ingested from external sources,
            grouped as one interaction per session) are excluded by default.
            Pass `true` to include them alongside native calls and
            conversations.
        - name: created_at_gte
          in: query
          required: false
          schema:
            type: string
            format: date-time
            title: Created At Greater Than or Equal
          description: >-
            Filter interactions created at or after this datetime (ISO 8601
            format). For external-channel interactions this compares against the
            call (leg start) time rather than the returned `created_at`
            ingestion timestamp.
        - name: created_at_lte
          in: query
          required: false
          schema:
            type: string
            format: date-time
            title: Created At Less Than or Equal
          description: >-
            Filter interactions created at or before this datetime (ISO 8601
            format). For external-channel interactions this compares against the
            call (leg start) time rather than the returned `created_at`
            ingestion timestamp.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - created_at
              - updated_at
              - started_at
              - ended_at
              - duration
              - status
            default: created_at
            title: Sort By
          description: Field to sort results by
        - name: sort_direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            title: Sort Direction
          description: Sort direction
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InteractionListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    InteractionListResponse:
      properties:
        interactions:
          items:
            $ref: '#/components/schemas/InteractionDetailsResponse'
          type: array
          title: Interactions
        total_count:
          type: integer
          title: Total Count
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        total_pages:
          type: integer
          title: Total Pages
        filters:
          type: object
          properties:
            status:
              anyOf:
                - type: string
                - type: 'null'
              title: Status
            modality:
              anyOf:
                - type: string
                  enum:
                    - voice
                    - text
                - type: 'null'
              title: Modality
            agent_id:
              anyOf:
                - type: string
                  format: uuid
                - type: 'null'
              title: Agent ID
            agent_version_id:
              anyOf:
                - type: string
                  format: uuid
                - type: 'null'
              title: Agent Version ID
            transferred:
              anyOf:
                - type: boolean
                - type: 'null'
              title: Transferred
            created_at_gte:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
              title: Created At Greater Than or Equal
            created_at_lte:
              anyOf:
                - type: string
                  format: date-time
                - type: 'null'
              title: Created At Less Than or Equal
          title: Filters
        sorting:
          type: object
          properties:
            sort_by:
              type: string
              title: Sort By
            sort_direction:
              type: string
              title: Sort Direction
          title: Sorting
      type: object
      required:
        - interactions
        - total_count
        - page
        - page_size
        - total_pages
      title: InteractionListResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InteractionDetailsResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        type:
          type: string
          enum:
            - call
            - conversation
            - email
            - sms
            - external_channel
          title: Type
          description: >-
            Identifies whether the interaction is a native call/conversation or
            an external-channel interaction.
        modality:
          anyOf:
            - $ref: '#/components/schemas/ModalityEnum'
            - type: 'null'
          description: >-
            Native interactions return `voice` or `text`. External-channel
            interactions return `null`.
        language:
          $ref: '#/components/schemas/LanguageEnum'
        from_number:
          anyOf:
            - type: string
              title: From Number
            - type: 'null'
          title: From Number
          description: >-
            Phone number for native interactions. External-channel interactions
            return `null`.
        to_number:
          anyOf:
            - type: string
              title: To Number
            - type: 'null'
          title: To Number
          description: >-
            Phone number for native interactions. External-channel interactions
            return `null`.
        status:
          type: string
          title: Status
        transferred:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Transferred
          description: >-
            Indicates if the interaction was transferred. External-channel
            interactions return `null`.
        handoff_metadata:
          anyOf:
            - $ref: '#/components/schemas/HandoffMetadata'
            - type: 'null'
          title: Handoff Metadata
          description: >-
            Metadata about the handoff when the interaction was transferred to
            an external provider (e.g. Five9). External-channel interactions
            return `null`.
        direction:
          anyOf:
            - type: string
              title: Direction
            - type: 'null'
          title: Direction
          description: >-
            The direction of the interaction (inbound/outbound).
            External-channel interactions return `null`.
        tags:
          type: array
          title: Tags
          description: Tags associated with the interaction
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              description:
                type: string
              color:
                type: string
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        duration:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration
        created_at:
          type: string
          format: date-time
          title: Created At
          description: >-
            For native interactions this is the record creation time. For
            external-channel interactions this is the underlying session's
            ingestion time. Note: `created_at` sorting and the
            `created_at_gte`/`created_at_lte` filters order external-channel
            interactions by their call (leg start) time, not by this ingestion
            timestamp, so a returned `created_at` value may fall outside the
            requested filter window.
        external_identifiers:
          anyOf:
            - type: object
              additionalProperties:
                type: string
            - type: 'null'
          title: External Identifiers
          description: External identifiers associated with the interaction
        params:
          anyOf:
            - type: object
              additionalProperties:
                type: string
            - type: 'null'
          title: Params
          description: Parameters associated with the interaction
        transcripts:
          items:
            anyOf:
              - $ref: '#/components/schemas/CallTranscriptResponse'
              - $ref: '#/components/schemas/ExternalChannelTranscriptResponse'
          type: array
          title: Transcripts
          description: Transcript item shape depends on the interaction `type`.
        recording_presigned_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Recording Presigned Url
          description: >-
            Presigned URL for the recording (for voice modality only).
            External-channel interactions return `null`.
        answered_by:
          anyOf:
            - $ref: '#/components/schemas/AnsweredByEnum'
            - type: 'null'
          title: Answered By
          description: >-
            Answered-by classification for native voice interactions.
            External-channel interactions return `null`.
        analyzers:
          type: array
          title: Analyzers
          description: List of analyzers configured for this interaction
          items:
            $ref: '#/components/schemas/AnalyzerResponse'
        analysis_results:
          type: array
          title: Analysis Results
          description: Results from analyzers that have completed
          items:
            $ref: '#/components/schemas/AnalysisResultResponse'
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
          description: The summary of the interaction if available
      type: object
      required:
        - id
        - type
        - status
        - started_at
        - created_at
        - transcripts
      title: InteractionDetailsResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ModalityEnum:
      type: string
      enum:
        - voice
        - text
      title: Modality
      description: The modality of the interaction - voice calls or text conversations
    LanguageEnum:
      type: string
      enum:
        - en
        - es
        - ar
      title: Language
      description: The language to use for the call - English (en) or Spanish (es)
    HandoffMetadata:
      type: object
      title: HandoffMetadata
      description: Metadata about a transfer to an external provider.
      properties:
        five9:
          anyOf:
            - $ref: '#/components/schemas/Five9HandoffMetadata'
            - type: 'null'
          title: Five9
          description: Five9 handoff details. Present when the transfer was to Five9.
    CallTranscriptResponse:
      properties:
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
        role:
          type: string
          title: Role
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        function_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Function Name
        arguments:
          anyOf:
            - type: object
            - type: 'null'
          title: Arguments
      type: object
      required:
        - text
        - role
        - timestamp
        - function_name
        - arguments
      title: CallTranscriptResponse
    ExternalChannelTranscriptResponse:
      properties:
        speaker:
          type: string
          title: Speaker
        text:
          type: string
          title: Text
        start:
          type: number
          title: Start
        end:
          type: number
          title: End
        confidence:
          type: number
          title: Confidence
        channel:
          type: string
          title: Channel
      type: object
      required:
        - speaker
        - text
        - start
        - end
        - confidence
      title: ExternalChannelTranscriptResponse
    AnsweredByEnum:
      type: string
      enum:
        - voicemail
        - human
        - no_answer
        - unknown
      title: Answered By
      description: >-
        Indicates how the call was answered - by a human, voicemail, or if there
        was no answer
    AnalyzerResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier for the analyzer
        prompt:
          type: string
          title: Prompt
          description: The prompt used for analysis
        output_config:
          type: object
          title: Output Config
          description: Configuration for the expected output format
          properties:
            type:
              type: string
              enum:
                - string
                - boolean
                - datetime
                - object
              description: The type of output expected
            properties:
              type: object
              description: >-
                Required when type is 'object'. Defines the structure of the
                object
              additionalProperties:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - string
                      - boolean
                      - datetime
      required:
        - id
        - prompt
        - output_config
      title: AnalyzerResponse
    AnalysisResultResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier for the analysis result
        analyzer_id:
          type: string
          format: uuid
          title: Analyzer Id
          description: Identifier of the analyzer that produced this result
        prompt:
          type: string
          title: Prompt
          description: The prompt used for analysis
        output_config:
          type: object
          title: Output Config
          description: Configuration for the expected output format
        result:
          type: object
          title: Result
          description: The analysis result, structure depends on the output_config
      required:
        - id
        - analyzer_id
        - prompt
        - output_config
        - result
      title: AnalysisResultResponse
    Five9HandoffMetadata:
      type: object
      title: Five9HandoffMetadata
      description: Details of a transfer to Five9.
      properties:
        conversation_id:
          type: string
          title: Conversation ID
          description: The Five9 conversation ID. Use this to correlate with Five9's API.
        tenant_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Tenant Name
          description: The Five9 tenant name used for the transfer.
        campaign_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Campaign Name
          description: The Five9 campaign the conversation was routed to.
        transferred_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Transferred At
          description: When the transfer occurred (ISO 8601).
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization

````