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

# Get Conversations

> Get all conversations of agents that user owns. With option to restrict to a specific agent.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/convai/conversations
openapi: 3.1.0
info:
  title: Threetone API Documentation
  description: >-
    This is the documentation for the Threetone API. You can use this API to use
    our service programmatically with API keys sent in the x-api-key header. You
    can create and manage API keys in the dashboard at
    https://threetone.in/app/developers/api-keys.
  version: '1.0'
servers:
  - url: https://api.threetone.in
    description: Production
security: []
paths:
  /v1/convai/conversations:
    get:
      tags:
        - Agents Platform
      summary: Get Conversations
      description: >-
        Get all conversations of agents that user owns. With option to restrict
        to a specific agent.
      operationId: get_conversation_histories_route
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Used for fetching next page. Cursor is returned in the response.
            title: Cursor
          description: Used for fetching next page. Cursor is returned in the response.
        - name: agent_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Agent id (agent_…) or speech engine external id (seng_), resolved
              to the same underlying resource.
            examples:
              - agent_3701k3ttaq12ewp8b7qv5rfyszkz
              - seng_3701k3ttaq12ewp8b7qv5rfyszkz
            title: Agent Id
          description: >-
            Agent id (agent_…) or speech engine external id (seng_), resolved to
            the same underlying resource.
        - name: visited_agent_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 50
              - type: 'null'
            description: >-
              Filter conversations where any of these agents participated. Can
              not exceed 50 values.
            title: Visited Agent Ids
          description: >-
            Filter conversations where any of these agents participated. Can not
            exceed 50 values.
        - name: visited_agent_branch_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 50
              - type: 'null'
            description: >-
              Filter conversations where any of these agent branches
              participated. Can not exceed 50 values.
            title: Visited Agent Branch Ids
          description: >-
            Filter conversations where any of these agent branches participated.
            Can not exceed 50 values.
        - name: triggered_procedure_ids
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 50
              - type: 'null'
            description: >-
              Filter conversations where any of these procedures were triggered.
              Can not exceed 50 values.
            title: Triggered Procedure Ids
          description: >-
            Filter conversations where any of these procedures were triggered.
            Can not exceed 50 values.
        - name: call_successful
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/EvaluationResultFilter'
              - type: 'null'
            description: The result of the success evaluation
            examples:
              - success
            title: Call Successful
          description: The result of the success evaluation
        - name: call_start_before_unix
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: >-
              Unix timestamp (in seconds) to filter conversations up to this
              start date.
            title: Call Start Before Unix
          description: >-
            Unix timestamp (in seconds) to filter conversations up to this start
            date.
        - name: call_start_after_unix
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: >-
              Unix timestamp (in seconds) to filter conversations after to this
              start date.
            title: Call Start After Unix
          description: >-
            Unix timestamp (in seconds) to filter conversations after to this
            start date.
        - name: call_duration_min_secs
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Minimum call duration in seconds.
            title: Call Duration Min Secs
          description: Minimum call duration in seconds.
        - name: call_duration_max_secs
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: Maximum call duration in seconds.
            title: Call Duration Max Secs
          description: Maximum call duration in seconds.
        - name: rating_max
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 5
                minimum: 1
              - type: 'null'
            description: Maximum overall rating (1-5).
            title: Rating Max
          description: Maximum overall rating (1-5).
        - name: rating_min
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                maximum: 5
                minimum: 1
              - type: 'null'
            description: Minimum overall rating (1-5).
            title: Rating Min
          description: Minimum overall rating (1-5).
        - name: has_feedback_comment
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            description: Filter conversations with user feedback comments.
            title: Has Feedback Comment
          description: Filter conversations with user feedback comments.
        - name: user_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter conversations by the user ID who initiated them.
            title: User Id
          description: Filter conversations by the user ID who initiated them.
        - name: evaluation_params
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Evaluation filters. Repeat param. Format: criteria_id:result.
              Example: eval=value_framing:success
            title: Evaluation Params
          description: >-
            Evaluation filters. Repeat param. Format: criteria_id:result.
            Example: eval=value_framing:success
        - name: data_collection_params
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Data collection filters. Repeat param. Format: id:op:value where
              op is one of eq|neq|gt|gte|lt|lte|in|exists|missing. For in,
              pipe-delimit values.
            title: Data Collection Params
          description: >-
            Data collection filters. Repeat param. Format: id:op:value where op
            is one of eq|neq|gt|gte|lt|lte|in|exists|missing. For in,
            pipe-delimit values.
        - name: data_collection_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Data collection field IDs to include in each conversation summary.
              Repeat param. When omitted, data_collection_results is not
              returned.
            title: Data Collection Ids
          description: >-
            Data collection field IDs to include in each conversation summary.
            Repeat param. When omitted, data_collection_results is not returned.
        - name: evaluation_criteria_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Evaluation criteria IDs to include in each conversation summary.
              Repeat param. When omitted, evaluation_criteria_results is not
              returned.
            title: Evaluation Criteria Ids
          description: >-
            Evaluation criteria IDs to include in each conversation summary.
            Repeat param. When omitted, evaluation_criteria_results is not
            returned.
        - name: tool_names
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter conversations by tool names used during the call.
            title: Tool Names
          description: Filter conversations by tool names used during the call.
        - name: tool_names_successful
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter conversations by tool names that had successful calls.
            title: Tool Names Successful
          description: Filter conversations by tool names that had successful calls.
        - name: tool_names_errored
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter conversations by tool names that had errored calls.
            title: Tool Names Errored
          description: Filter conversations by tool names that had errored calls.
        - name: include_invalid_tool_calls
          in: query
          required: false
          schema:
            type: boolean
            description: Also match tool calls that never ran.
            default: false
            title: Include Invalid Tool Calls
          description: Also match tool calls that never ran.
        - name: main_languages
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter conversations by detected main language (language code).
            title: Main Languages
          description: Filter conversations by detected main language (language code).
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            description: >-
              How many conversations to return at maximum. Can not exceed 100,
              defaults to 30.
            default: 30
            title: Page Size
          description: >-
            How many conversations to return at maximum. Can not exceed 100,
            defaults to 30.
        - name: summary_mode
          in: query
          required: false
          schema:
            enum:
              - exclude
              - include
            type: string
            description: Whether to include transcript summaries in the response.
            default: exclude
            title: Summary Mode
          description: Whether to include transcript summaries in the response.
        - name: conversation_initiation_source
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/ConversationInitiationSource'
              - type: 'null'
            title: Conversation Initiation Source
        - name: text_only
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Text Only
        - name: conversation_product_type
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/ConversationProduct'
              - type: 'null'
            description: Restrict results to a single conversation product surface.
            title: Conversation Product Type
          description: Restrict results to a single conversation product surface.
        - name: branch_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter conversations by branch ID.
            title: Branch Id
          description: Filter conversations by branch ID.
        - name: version_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter conversations by version ID.
            title: Version Id
          description: Filter conversations by version ID.
        - name: parent_conversation_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter conversations by parent conversation ID for subagent
              conversations.
            title: Parent Conversation Id
          description: >-
            Filter conversations by parent conversation ID for subagent
            conversations.
        - name: topic_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: Filter conversations by topic IDs assigned during topic discovery.
            title: Topic Ids
          description: Filter conversations by topic IDs assigned during topic discovery.
        - name: exclude_statuses
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  enum:
                    - initiated
                    - in-progress
                    - processing
                    - done
                    - failed
                  type: string
              - type: 'null'
            description: >-
              Exclude conversations with the given statuses. Useful for hiding
              in-progress / processing conversations from list views.
            title: Exclude Statuses
          description: >-
            Exclude conversations with the given statuses. Useful for hiding
            in-progress / processing conversations from list views.
        - name: tag_ids
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Filter conversations by conversation tag IDs assigned via the
              conversation-tags endpoints.
            title: Tag Ids
          description: >-
            Filter conversations by conversation tag IDs assigned via the
            conversation-tags endpoints.
        - name: workflow_node_entered_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter conversations to only those that entered the given node.
            title: Workflow Node Entered Id
          description: Filter conversations to only those that entered the given node.
        - name: termination_reasons
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Filter conversations by their stored termination_reason
              (metadata.termination_reason). Repeat param to match any of
              several.
            title: Termination Reasons
          description: >-
            Filter conversations by their stored termination_reason
            (metadata.termination_reason). Repeat param to match any of several.
        - name: guardrail_types
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/GuardrailType'
              - type: 'null'
            description: >-
              Filter to conversations where a guardrail of any of these types
              triggered (metadata.triggered_guardrails.guardrail_type). Repeat
              param to match any of several.
            title: Guardrail Types
          description: >-
            Filter to conversations where a guardrail of any of these types
            triggered (metadata.triggered_guardrails.guardrail_type). Repeat
            param to match any of several.
        - name: custom_guardrail_names
          in: query
          required: false
          schema:
            anyOf:
              - items:
                  type: string
                type: array
              - type: 'null'
            description: >-
              Filter to conversations where a custom guardrail with any of these
              names triggered (metadata.triggered_guardrails.guardrail_name).
              Only custom guardrails carry a name. Repeat param to match any of
              several.
            title: Custom Guardrail Names
          description: >-
            Filter to conversations where a custom guardrail with any of these
            names triggered (metadata.triggered_guardrails.guardrail_name). Only
            custom guardrails carry a name. Repeat param to match any of
            several.
        - name: sort_direction
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SortDirection'
            description: >-
              The direction to sort conversations by call start time. Defaults
              to descending (newest first).
            default: desc
          description: >-
            The direction to sort conversations by call start time. Defaults to
            descending (newest first).
        - name: x-api-key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Your API key for programmatic access. Send it in the x-api-key
              header; you can create and manage keys from the Developers page.
            title: X-Api-Key
          description: >-
            Your API key for programmatic access. Send it in the x-api-key
            header; you can create and manage keys from the Developers page.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetConversationsPageResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EvaluationResultFilter:
      type: string
      enum:
        - success
        - failure
        - unknown
        - error
      title: EvaluationResultFilter
    ConversationInitiationSource:
      type: string
      enum:
        - unknown
        - android_sdk
        - node_js_sdk
        - react_native_sdk
        - react_sdk
        - js_sdk
        - python_sdk
        - widget
        - sip_trunk
        - twilio
        - exotel
        - genesys
        - avaya
        - audiocodes
        - swift_sdk
        - whatsapp
        - twilio_sms
        - flutter_sdk
        - zendesk_integration
        - slack_integration
        - telegram_integration
        - intercom_integration
        - freshdesk_integration
        - salesforce_integration
        - template_preview
        - genesys_bot_connector
        - subagent_tool
      title: ConversationInitiationSource
      description: Enum representing the possible sources for conversation initiation.
      default: unknown
    ConversationProduct:
      type: string
      enum:
        - agents
        - speech_engine
      title: ConversationProduct
      description: Which product surface owns this agent document.
    GuardrailType:
      type: string
      enum:
        - custom
        - prompt_injection
        - self_harm_intent
        - violence_graphic
        - sexual
        - violence
        - harassment
        - sexual_minors
        - self_harm
        - self_harm_instructions
        - harassment_threatening
        - hate
        - hate_threatening
        - profanity
        - religion_or_politics
        - medical_and_legal
        - guardrail
      title: GuardrailType
    SortDirection:
      type: string
      enum:
        - asc
        - desc
      title: SortDirection
    GetConversationsPageResponseModel:
      properties:
        conversations:
          items:
            $ref: '#/components/schemas/ConversationSummaryResponseModel'
          type: array
          title: Conversations
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
        - conversations
        - has_more
      title: GetConversationsPageResponseModel
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ConversationSummaryResponseModel:
      properties:
        agent_id:
          type: string
          title: Agent Id
        branch_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Branch Id
        version_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Version Id
        agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Name
        conversation_id:
          type: string
          title: Conversation Id
        start_time_unix_secs:
          type: integer
          title: Start Time Unix Secs
        call_duration_secs:
          type: integer
          title: Call Duration Secs
        message_count:
          type: integer
          title: Message Count
        status:
          type: string
          enum:
            - initiated
            - in-progress
            - processing
            - done
            - failed
          title: Status
        termination_reason:
          type: string
          title: Termination Reason
          default: ''
        call_successful:
          $ref: '#/components/schemas/EvaluationSuccessResult'
        call_success_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Call Success Score
        transcript_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Transcript Summary
        call_summary_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Call Summary Title
        main_language:
          anyOf:
            - type: string
            - type: 'null'
          title: Main Language
        conversation_initiation_source:
          anyOf:
            - $ref: '#/components/schemas/ConversationInitiationSource'
            - type: 'null'
        tool_names:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tool Names
        direction:
          anyOf:
            - $ref: '#/components/schemas/TelephonyDirection'
            - type: 'null'
        rating:
          anyOf:
            - type: number
            - type: 'null'
          title: Rating
        sentiment_analysis:
          anyOf:
            - $ref: '#/components/schemas/ConversationSentimentAnalysis'
            - type: 'null'
        data_collection_results:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Data Collection Results
        evaluation_criteria_results:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/EvaluationCriteriaSummaryResult'
              type: object
            - type: 'null'
          title: Evaluation Criteria Results
        tag_ids:
          items:
            type: string
          type: array
          title: Tag Ids
          description: Conversation tag ids assigned to this conversation.
      type: object
      required:
        - agent_id
        - conversation_id
        - start_time_unix_secs
        - call_duration_secs
        - message_count
        - status
        - call_successful
      title: ConversationSummaryResponseModel
    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
    EvaluationSuccessResult:
      type: string
      enum:
        - success
        - failure
        - unknown
      title: EvaluationSuccessResult
    TelephonyDirection:
      type: string
      enum:
        - inbound
        - outbound
      title: TelephonyDirection
      default: inbound
    ConversationSentimentAnalysis:
      properties:
        overall_label:
          type: string
          enum:
            - positive
            - neutral
            - negative
          title: Overall Label
        overall_sentiment_score:
          type: number
          maximum: 1
          minimum: -1
          title: Overall Sentiment Score
        overall_frustration_score:
          type: number
          maximum: 1
          minimum: 0
          title: Overall Frustration Score
        min_user_sentiment_score:
          type: number
          maximum: 1
          minimum: -1
          title: Min User Sentiment Score
        max_user_frustration_score:
          type: number
          maximum: 1
          minimum: 0
          title: Max User Frustration Score
        num_scored_user_turns:
          type: integer
          minimum: 0
          title: Num Scored User Turns
      type: object
      required:
        - overall_label
        - overall_sentiment_score
        - overall_frustration_score
        - min_user_sentiment_score
        - max_user_frustration_score
        - num_scored_user_turns
      title: ConversationSentimentAnalysis
    EvaluationCriteriaSummaryResult:
      properties:
        result:
          $ref: '#/components/schemas/EvaluationSuccessResult'
        score:
          anyOf:
            - type: integer
            - type: 'null'
          title: Score
        max_score:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Score
      type: object
      required:
        - result
      title: EvaluationCriteriaSummaryResult

````