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

# Get a conversation

> Returns one Conversation under conversations:read and channels:read. Messages, Facts, and participants require their additional permissions; the operation is side-effect free and retry-safe.



## OpenAPI

````yaml https://api.getarbol.com/openapi.json get /conversations/{id}
openapi: 3.1.2
info:
  contact:
    email: support@getarbol.com
    name: Arbol
    url: https://docs.getarbol.com
  description: >-
    Provider-neutral API for creating and operating Arbol agents, contacts,
    conversations, channels, knowledge, integrations, and evaluations. Every
    request is bound to one Auth0 Organization.
  title: Arbol API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.getarbol.com/v1
security: []
paths:
  /conversations/{id}:
    get:
      tags:
        - Conversations
      summary: Get a conversation
      description: >-
        Returns one Conversation under conversations:read and channels:read.
        Messages, Facts, and participants require their additional permissions;
        the operation is side-effect free and retry-safe.
      operationId: getConversation
      parameters:
        - in: path
          required: true
          name: id
          schema:
            $ref: '#/components/schemas/ArbolResourceId'
        - in: query
          name: expand
          schema:
            maxItems: 3
            type: array
            items:
              type: string
              enum:
                - messages
                - participants
                - facts
          allowEmptyValue: true
          allowReserved: true
          explode: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '400':
          description: >-
            Inferable validation failure or a non-inferable malformed transport
            request.
          content:
            application/json:
              schema:
                oneOf:
                  - oneOf:
                      - $ref: '#/components/schemas/BadRequest'
                      - $ref: '#/components/schemas/UndefinedError'
                  - $ref: '#/components/schemas/TransportBadRequestError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Unauthorized'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '403':
          description: The caller is not allowed to perform this operation.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/Forbidden'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/NotFound'
                  - $ref: '#/components/schemas/UndefinedError'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
      security:
        - userOAuth:
            - org:use
            - conversations:read
            - channels:read
        - machineOAuth:
            - conversations:read
            - channels:read
components:
  schemas:
    ArbolResourceId:
      type: string
      maxLength: 64
      pattern: >-
        ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
      description: >-
        Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup
        determine its resource type.
      examples:
        - agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31
      title: Arbol resource ID
    ConversationDetail:
      type: object
      properties:
        agentId:
          anyOf:
            - $ref: '#/components/schemas/ArbolResourceId'
            - type: 'null'
        channelKind:
          $ref: '#/components/schemas/ChannelKind'
        closeReason:
          anyOf:
            - $ref: '#/components/schemas/ConversationCloseReason'
            - type: 'null'
        contactId:
          anyOf:
            - $ref: '#/components/schemas/ArbolResourceId'
            - type: 'null'
        createdAt:
          $ref: '#/components/schemas/IsoDatetime'
        direction:
          $ref: '#/components/schemas/ConversationDirection'
        durationSeconds:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 9007199254740991
            - type: 'null'
        endedAt:
          anyOf:
            - $ref: '#/components/schemas/IsoDatetime'
            - type: 'null'
        id:
          $ref: '#/components/schemas/ArbolResourceId'
        language:
          anyOf:
            - type: string
              maxLength: 35
            - type: 'null'
        lastMessageAt:
          anyOf:
            - $ref: '#/components/schemas/IsoDatetime'
            - type: 'null'
        messageCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        originKind:
          $ref: '#/components/schemas/ConversationOriginKind'
        outcome:
          anyOf:
            - $ref: '#/components/schemas/ConversationOutcome'
            - type: 'null'
        sentiment:
          anyOf:
            - $ref: '#/components/schemas/ConversationSentiment'
            - type: 'null'
        startedAt:
          $ref: '#/components/schemas/IsoDatetime'
        status:
          $ref: '#/components/schemas/ConversationStatus'
        subjectContactId:
          anyOf:
            - $ref: '#/components/schemas/ArbolResourceId'
            - type: 'null'
        summary:
          anyOf:
            - type: string
              maxLength: 8000
            - type: 'null'
        title:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
        updatedAt:
          $ref: '#/components/schemas/IsoDatetime'
        facts:
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/Fact'
        lineAddress:
          anyOf:
            - type: string
              maxLength: 320
            - type: 'null'
        messages:
          maxItems: 1000
          type: array
          items:
            type: object
            properties:
              content:
                type: string
                maxLength: 64000
              contentFormat:
                type: string
                enum:
                  - text
                  - markdown
              id:
                $ref: '#/components/schemas/ArbolResourceId'
              occurredAt:
                $ref: '#/components/schemas/IsoDatetime'
              payload:
                anyOf:
                  - type: object
                    properties:
                      interrupted:
                        type: boolean
                      latency:
                        type: object
                        properties:
                          e2eMs:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          llmMs:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          llmTtfbMs:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          sttMs:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          ttsMs:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                        additionalProperties: false
                      source:
                        type: object
                        properties:
                          hasMedia:
                            type: boolean
                          kind:
                            type: string
                            enum:
                              - text
                              - button
                              - list
                              - audio
                              - image
                              - document
                              - sticker
                          transcribed:
                            type: boolean
                        required:
                          - hasMedia
                          - kind
                        additionalProperties: false
                      sourceMedium:
                        type: string
                        maxLength: 40
                      tool:
                        type: object
                        properties:
                          input:
                            type: string
                            maxLength: 8000
                          latencyMs:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          name:
                            type: string
                            minLength: 1
                            maxLength: 256
                          output:
                            type: string
                            maxLength: 8000
                          status:
                            type: string
                            enum:
                              - completed
                              - failed
                              - pending
                          truncated:
                            type: boolean
                        required:
                          - name
                          - status
                        additionalProperties: false
                    additionalProperties: false
                  - type: 'null'
              role:
                type: string
                enum:
                  - contact
                  - agent
                  - user
                  - system
                  - tool
              seq:
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
              - content
              - contentFormat
              - id
              - occurredAt
              - payload
              - role
              - seq
            additionalProperties: false
        participants:
          maxItems: 20
          type: array
          items:
            type: object
            properties:
              contactId:
                $ref: '#/components/schemas/ArbolResourceId'
              name:
                anyOf:
                  - type: string
                    maxLength: 320
                  - type: 'null'
              phone:
                anyOf:
                  - type: string
                    maxLength: 64
                  - type: 'null'
            required:
              - contactId
              - name
              - phone
            additionalProperties: false
      required:
        - agentId
        - channelKind
        - closeReason
        - contactId
        - createdAt
        - direction
        - durationSeconds
        - endedAt
        - id
        - language
        - lastMessageAt
        - messageCount
        - originKind
        - outcome
        - sentiment
        - startedAt
        - status
        - subjectContactId
        - summary
        - title
        - updatedAt
        - lineAddress
      additionalProperties: false
      title: Conversation detail
    BadRequest:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: BAD_REQUEST
        status:
          const: 400
        message:
          type: string
        data:
          type: object
          properties:
            issues:
              maxItems: 20
              type: array
              items:
                type: object
                properties:
                  message:
                    type: string
                    maxLength: 500
                  path:
                    maxItems: 16
                    type: array
                    items:
                      anyOf:
                        - type: string
                          maxLength: 120
                        - type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                required:
                  - message
                additionalProperties: false
            truncated:
              type: boolean
          required:
            - issues
            - truncated
          additionalProperties: false
      required:
        - defined
        - inferable
        - code
        - status
        - message
        - data
    UndefinedError:
      type: object
      properties:
        defined:
          const: false
        inferable:
          type: boolean
        code:
          type: string
        status:
          type: number
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    TransportBadRequestError:
      additionalProperties: false
      properties:
        code:
          const: BAD_REQUEST
        data: {}
        defined:
          const: false
        inferable:
          const: false
        message:
          type: string
      required:
        - defined
        - inferable
        - code
        - message
      type: object
    Unauthorized:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: UNAUTHORIZED
        status:
          const: 401
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    Forbidden:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: FORBIDDEN
        status:
          const: 403
        message:
          type: string
        data:
          type: object
          properties:
            missingPermissions:
              maxItems: 10
              type: array
              items:
                $ref: '#/components/schemas/AuthPermission'
          required:
            - missingPermissions
          additionalProperties: false
      required:
        - defined
        - inferable
        - code
        - status
        - message
    NotFound:
      type: object
      properties:
        defined:
          const: true
        inferable:
          type: boolean
        code:
          const: NOT_FOUND
        status:
          const: 404
        message:
          type: string
        data: {}
      required:
        - defined
        - inferable
        - code
        - status
        - message
    ChannelKind:
      type: string
      enum:
        - voice
        - whatsapp
        - telegram
        - slack
        - email
        - web
      description: Conversation transport family.
      examples:
        - voice
      title: Channel kind
    ConversationCloseReason:
      type: string
      enum:
        - completed
        - inactivity
        - handoff
        - provider_migration
        - error
        - manual
      description: Reason recorded when a Conversation enters its closed state.
      examples:
        - completed
      title: Conversation close reason
    IsoDatetime:
      type: string
      format: date-time
      pattern: >-
        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
      description: ISO 8601 timestamp with an explicit UTC offset.
      examples:
        - '2026-08-29T14:30:00Z'
      title: ISO timestamp
    ConversationDirection:
      type: string
      enum:
        - inbound
        - outbound
      description: Direction of a Conversation relative to the organization.
      examples:
        - inbound
      title: Conversation direction
    ConversationOriginKind:
      type: string
      enum:
        - inbound
        - manual
        - automation
        - import
        - test
      description: Source that created the Conversation record.
      examples:
        - manual
      title: Conversation origin
    ConversationOutcome:
      type: string
      enum:
        - successful
        - unsuccessful
        - follow_up_needed
        - no_answer
      description: Structured business outcome assigned to a Conversation.
      examples:
        - successful
      title: Conversation outcome
    ConversationSentiment:
      type: string
      enum:
        - positive
        - neutral
        - negative
      description: Coarse sentiment assigned to a Conversation.
      examples:
        - neutral
      title: Conversation sentiment
    ConversationStatus:
      type: string
      enum:
        - open
        - closed
      description: Durable lifecycle state of a Conversation.
      examples:
        - open
      title: Conversation status
    Fact:
      type: object
      properties:
        confidence:
          anyOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
        definition:
          type: object
          properties:
            description:
              anyOf:
                - type: string
                  maxLength: 2000
                - type: 'null'
            id:
              $ref: '#/components/schemas/ArbolResourceId'
            identifier:
              type: string
              minLength: 1
              maxLength: 100
            kind:
              $ref: '#/components/schemas/DefinitionKind'
            subjectKind:
              $ref: '#/components/schemas/DefinitionSubject'
            valueType:
              $ref: '#/components/schemas/DefinitionValueType'
          required:
            - description
            - id
            - identifier
            - kind
            - subjectKind
            - valueType
          additionalProperties: false
        id:
          $ref: '#/components/schemas/ArbolResourceId'
        observedAt:
          $ref: '#/components/schemas/IsoDatetime'
        reason:
          anyOf:
            - type: string
              maxLength: 2000
            - type: 'null'
        recordedAt:
          $ref: '#/components/schemas/IsoDatetime'
        setBy:
          $ref: '#/components/schemas/FactActorKind'
        subject:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/ArbolResourceId'
            type:
              $ref: '#/components/schemas/DefinitionSubject'
          required:
            - id
            - type
          additionalProperties: false
        value:
          $ref: '#/components/schemas/FactValue'
        verificationStatus:
          $ref: '#/components/schemas/FactVerificationStatus'
      required:
        - confidence
        - definition
        - id
        - observedAt
        - reason
        - recordedAt
        - setBy
        - subject
        - value
        - verificationStatus
      additionalProperties: false
      description: >-
        Recorded immutable assertion with its Definition snapshot, provenance,
        and review state.
      title: Fact assertion
    AuthPermission:
      type: string
      enum:
        - agent-evaluations:read
        - agent-evaluations:run
        - agent-evaluations:write
        - agents:read
        - agents:write
        - analytics:read
        - arbi:use
        - channels:read
        - channels:write
        - contacts:read
        - contacts:write
        - conversations:read
        - conversations:transcript
        - conversations:write
        - definitions:read
        - definitions:write
        - facts:read
        - facts:write
        - integrations:read
        - integrations:write
        - knowledge:read
        - knowledge:write
        - org:manage
        - org:use
      description: >-
        One permission from the closed Arbol API vocabulary accepted from a
        verified Auth0 token.
      examples:
        - agents:read
      title: API permission
    DefinitionKind:
      type: string
      enum:
        - attribute
        - assessment
        - category
        - metric
      description: Semantic class of an organization-owned Definition.
      examples:
        - attribute
      title: Definition kind
    DefinitionSubject:
      type: string
      enum:
        - contact
        - conversation
      description: Resource type to which a Definition may be asserted.
      examples:
        - contact
      title: Definition subject
    DefinitionValueType:
      type: string
      enum:
        - text
        - number
        - boolean
        - date
        - option
      description: Validated value representation accepted by a Definition.
      examples:
        - option
      title: Definition value type
    FactActorKind:
      type: string
      enum:
        - ai
        - user
        - system
        - import
        - rule
      description: Origin category recorded for a Fact assertion.
      examples:
        - user
      title: Fact actor kind
    FactValue:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              const: text
            value:
              type: string
              maxLength: 8000
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: number
            value:
              type: number
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: boolean
            value:
              type: boolean
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: date
            value:
              type: string
              format: date
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
          required:
            - type
            - value
          additionalProperties: false
        - type: object
          properties:
            optionId:
              $ref: '#/components/schemas/ArbolResourceId'
            type:
              type: string
              const: option
            label:
              anyOf:
                - type: string
                  minLength: 1
                  maxLength: 160
                - type: 'null'
          required:
            - optionId
            - type
            - label
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              const: unset
          required:
            - type
          additionalProperties: false
      description: >-
        Typed value of an immutable Fact assertion; unset is an explicit
        tombstone.
      title: Fact value
    FactVerificationStatus:
      type: string
      enum:
        - unreviewed
        - confirmed
        - rejected
      description: Human review state of a Fact assertion.
      examples:
        - unreviewed
      title: Fact verification status
  headers:
    RequestId:
      description: >-
        Opaque request correlation identifier. Include it when contacting Arbol
        support.
      schema:
        type: string
        maxLength: 128
  securitySchemes:
    userOAuth:
      description: >-
        Organization-scoped Auth0 user access token issued to an approved
        first-party client or exchanged by a trusted OBO resource server.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.getarbol.com/authorize
          scopes:
            agent-evaluations:read: Read Agent evaluation suites, runs, and results.
            agent-evaluations:run: Execute and cancel Agent evaluation runs.
            agent-evaluations:write: Create and update Agent evaluation suites.
            agents:read: Read Agents and their explicitly requested expansions.
            agents:write: Create, update, and delete Agents.
            analytics:read: Read organization analytics.
            arbi:use: Use the personal Arbi workspace.
            channels:read: Read Agent channels.
            channels:write: Create, update, authorize, and delete Agent channels.
            contacts:read: Read Contacts and their explicitly requested expansions.
            contacts:write: Create, update, merge, import, and delete Contacts.
            conversations:read: Read Conversation metadata.
            conversations:transcript: Read Conversation messages and media evidence.
            conversations:write: Create and process Conversations.
            definitions:read: Read Definitions and Definition usage.
            definitions:write: Create, update, and retire Definitions.
            facts:read: Read current and historical Facts.
            facts:write: Assert typed Facts.
            integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence.
            integrations:write: Authorize accounts and assign exact tool access.
            knowledge:read: Read Knowledge documents and search indexed content.
            knowledge:write: Create, index, update, and delete Knowledge documents.
            org:manage: Update the Organization and administer its members.
            org:use: Use Arbol as a member of the selected Auth0 Organization.
          tokenUrl: https://auth.getarbol.com/oauth/token
      type: oauth2
    machineOAuth:
      description: >-
        Organization-bound Auth0 client-credentials token. The client grant must
        contain every operation scope.
      flows:
        clientCredentials:
          scopes:
            agent-evaluations:read: Read Agent evaluation suites, runs, and results.
            agent-evaluations:run: Execute and cancel Agent evaluation runs.
            agent-evaluations:write: Create and update Agent evaluation suites.
            agents:read: Read Agents and their explicitly requested expansions.
            agents:write: Create, update, and delete Agents.
            analytics:read: Read organization analytics.
            channels:read: Read Agent channels.
            channels:write: Create, update, authorize, and delete Agent channels.
            contacts:read: Read Contacts and their explicitly requested expansions.
            contacts:write: Create, update, merge, import, and delete Contacts.
            conversations:read: Read Conversation metadata.
            conversations:transcript: Read Conversation messages and media evidence.
            conversations:write: Create and process Conversations.
            definitions:read: Read Definitions and Definition usage.
            definitions:write: Create, update, and retire Definitions.
            facts:read: Read current and historical Facts.
            facts:write: Assert typed Facts.
            integrations:read: Discover integrations, tools, accounts, and tool-bearing evidence.
            integrations:write: Authorize accounts and assign exact tool access.
            knowledge:read: Read Knowledge documents and search indexed content.
            knowledge:write: Create, index, update, and delete Knowledge documents.
            org:manage: Update the Organization and administer its members.
          tokenUrl: https://auth.getarbol.com/oauth/token
      type: oauth2

````