---
title: "Get conversation by ID"
method: GET
path: "/conversations/{conversationId}"
tags: ["Conversations"]
---

# Get conversation by ID

`GET /conversations/{conversationId}`

Retrieve a specific conversation with its full message history.

**Overview:**

Returns the complete conversation including all messages, citations,
feedback, and metadata. Messages can be paginated for long conversations.

**Message Pagination:**

For conversations with many messages, use pagination parameters:

- `page`: Page number (default: 1)
- `limit`: Messages per page (default: 10)
- `sortBy`: Sort field (default: createdAt)
- `sortOrder`: 'asc' or 'desc' (default: desc)

**Access Control:**

Users can access conversations they own or that have been shared with them.

## Path parameters

- `conversationId` string, objectId, required

## Query parameters

- `page` integer
- `limit` integer
- `sortBy` 'createdAt' | 'messageType' | 'content'
- `sortOrder` 'asc' | 'desc'
- `search` string
- `startDate` string, date-time
- `endDate` string, date-time
- `shared` boolean
- `messageType` 'user_query' | 'bot_response' | 'error' | 'feedback' | 'system'

## Response `200`

Conversation with paginated messages, applied filter metadata, and request metadata

- object
  - `conversation` object
    - `id` string, objectId — Unique conversation identifier
    - `title` string — Conversation title
    - `initiator` string, objectId — User who started the conversation
    - `createdAt` string, date-time
    - `isShared` boolean
    - `sharedWith` object[]
      - `userId` string, objectId
      - `accessLevel` 'read' | 'write'
    - `status` 'None' | 'Inprogress' | 'Complete' | 'Failed'
    - `failReason` string — Populated only when `status` is `Failed`
    - `messages` object[] — Page of messages, sliced by `pagination` and ordered by `sortingMessages`
      - `_id` string, objectId
      - `messageType` 'user_query' | 'bot_response' | 'error' | 'feedback' | 'system'
      - `content` string
      - `contentFormat` 'MARKDOWN' | 'JSON' | 'HTML'
      - `confidence` 'Very High' | 'High' | 'Medium' | 'Low' | 'Unknown', nullable — AI confidence in the answer. Present only on `bot_response` messages, and only when the model emitted a trailing confidence block. This field is now optional and nullable; it was previously always present and non-nullable. Treat a missing or `null` value as "no confidence reported" and guard before using it. Change effective in SDK v1.2.0 (v1.1.0 and earlier always populated it).
      - `citations` object[] — Citations attached to this message. `citationData` is the populated citation document.
        - `citationId` string, objectId
        - `citationData` Citation — A populated citation document. Represents a single chunk of source content (e.g. a passage from a document or record) referenced by an AI response, together with its provenance metadata.
          - `_id` string, objectId, required
          - `content` string, required — The cited text chunk
          - `chunkIndex` integer, required — Index of this chunk within the source record
          - `citationType` string, required — Source type identifier (e.g. `vectordb|document`)
          - `metadata` PersistedSemanticSearchCitationMetadata, required — Citation metadata as persisted in MongoDB. Required fields mirror the Mongoose schema's `required: true` flags; the rest are optional and may come through as `null` because the AI retrieval service emits explicit nulls for absent fields.
            - `orgId` string, required
            - `mimeType` string, required
            - `recordId` string, required
            - `recordName` string, required
            - `origin` string, required
            - `recordVersion` integer, nullable
            - `extension` string, nullable
            - `webUrl` string, nullable
            - `previewRenderable` boolean, nullable
            - `hideWeburl` boolean, nullable
            - `connector` string, nullable
            - `recordType` string, nullable
            - `blockNum` number[], nullable
            - `pageNum` number[], nullable
            - `sheetNum` number, nullable
            - `sheetName` string, nullable
            - `bounding_box` PersistedSemanticSearchBoundingBox[], nullable
              - …
            - `blockType` string, nullable — Block type for this citation. Common values: `text`, `image`, `table_row`, `table`, `record_summary` (whole-record semantic summary chunk).
            - `blockText` string, nullable
            - `departments` string[], nullable
            - `languages` string[], nullable
            - `topics` string[], nullable
          - `createdAt` string, date-time, required
          - `updatedAt` string, date-time, required
      - `followUpQuestions` FollowUpQuestion[]
        - `question` string — The suggested question text
        - `confidence` string — Confidence level for this suggestion
        - `reasoning` string — Why this question might be relevant
      - `feedback` MessageFeedback[]
        - `isHelpful` boolean — Overall helpfulness rating
        - `ratings` object
          - `accuracy` integer — How accurate was the information (1-5)
          - `relevance` integer — How relevant was the response (1-5)
          - `completeness` integer — How complete was the answer (1-5)
          - `clarity` integer — How clear was the explanation (1-5)
        - `categories` string[] — Categories of issues or positive attributes identified
        - `comments` object
          - `positive` string — What was good about the response
          - `negative` string — What could be improved
          - `suggestions` string — Specific suggestions for improvement
        - `citationFeedback` object[] — Feedback on individual citations
          - `_id` string, objectId — Auto-generated sub-document identifier
          - `citationId` string, objectId
          - `isRelevant` boolean
          - `relevanceScore` integer
          - `comment` string
        - `followUpQuestionsHelpful` boolean — Were the suggested follow-up questions helpful
        - `unusedFollowUpQuestions` string[] — Follow-up questions that were suggested but not used by the user
        - `source` 'user' | 'system' | 'admin' | 'auto' — Origin of the feedback. Always present in responses (server applies the default `user`).
        - `feedbackProvider` string, objectId — User who submitted the feedback
        - `timestamp` integer — Time the feedback was created, stored as a Number (epoch milliseconds) with a server-side default of `Date.now`, so always present in responses. Not an ISO 8601 datetime.
        - `revisions` object[] — Audit trail of edits to this feedback entry
          - `_id` string, objectId — Auto-generated sub-document identifier
          - `updatedFields` string[] — Names of feedback fields modified in this revision
          - `previousValues` object — Map of previously-set values for the fields named in `updatedFields`, keyed by field name. Stored as a Mongoose Map of Mixed values.
          - `updatedBy` string, objectId
          - `updatedAt` integer — Time the revision was recorded, as epoch milliseconds.
        - `metrics` object — Optional telemetry captured alongside the feedback
          - `timeToFeedback` number — Time from response delivery to feedback submission
          - `userInteractionTime` number — Total time the user spent reviewing the response
          - `feedbackSessionId` string
          - `userAgent` string
          - `platform` string
      - `referenceData` object[] — Reference IDs surfaced from tool responses, used for follow-up queries
        - `name` string — Display name shown to the user.
        - `id` string — Technical identifier (numeric ID, UUID, etc.).
        - `type` string — Item type (e.g. `project`, `issue`, `file`, `notebook`, `page`).
        - `app` string — Source application (e.g. `jira`, `confluence`, `sharepoint`, `slack`, `drive`, `gmail`).
        - `webUrl` string — URL to open the item in a browser.
        - `metadata` object — App-specific fields keyed by name (e.g. `key` for a Jira project, `siteId` for a SharePoint document).
      - `modelInfo` ConversationModelInfo — AI model configuration recorded against a conversation or message.
        - `modelKey` string — Stable identifier of the configured model record
        - `modelName` string — Provider-facing model name (e.g. `gpt-4o-mini`)
        - `modelProvider` string — Provider key (e.g. `openai`, `anthropic`)
        - `modelFriendlyName` string — Human-readable display name
        - `chatMode` string — Chat mode used for this turn (e.g. `quick`, `internal_search`)
      - `appliedFilters` object
        - `apps` AppliedFilterNode[]
          - `id` string — Unique identifier of the filter node
          - `name` string — Display name of the filter node
          - `nodeType` string — Type of the node (e.g. app, recordGroup, folder, record)
          - `connector` string — Connector identifier associated with this node
        - `kb` AppliedFilterNode[]
          - `id` string — Unique identifier of the filter node
          - `name` string — Display name of the filter node
          - `nodeType` string — Type of the node (e.g. app, recordGroup, folder, record)
          - `connector` string — Connector identifier associated with this node
      - `attachments` ChatAttachmentRef[] — Files uploaded for this message turn (see `POST /conversations/attachments/upload`).
        - `recordId` string, required — Attachment record id returned from the upload endpoint.
        - `recordName` string — Original display name of the file when known.
        - `mimeType` string — MIME type of the uploaded file.
        - `extension` string — File extension (e.g. `pdf`).
        - `virtualRecordId` string — Optional synthetic record id used by the graph layer.
      - `metadata` object
        - `processingTimeMs` number
        - `modelVersion` string
        - `aiTransactionId` string
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
    - `modelInfo` ConversationModelInfo — AI model configuration recorded against a conversation or message.
      - `modelKey` string — Stable identifier of the configured model record
      - `modelName` string — Provider-facing model name (e.g. `gpt-4o-mini`)
      - `modelProvider` string — Provider key (e.g. `openai`, `anthropic`)
      - `modelFriendlyName` string — Human-readable display name
      - `chatMode` string — Chat mode used for this turn (e.g. `quick`, `internal_search`)
    - `pagination` object — Pagination over the conversation's messages. Messages are paginated backwards (newest first), so `messageRange.start`/`messageRange.end` refer to 1-based positions within the full message list.
      - `page` integer
      - `limit` integer
      - `totalCount` integer — Total number of messages in the conversation
      - `totalPages` integer
      - `hasNextPage` boolean — True if there are older messages available
      - `hasPrevPage` boolean — True if there are newer messages available
      - `messageRange` object
        - `start` integer
        - `end` integer
    - `access` object
      - `isOwner` boolean
      - `accessLevel` 'read' | 'write'
  - `filters` object — Summary of which filter/sort/pagination parameters were applied to this request, plus the catalog of options available on this endpoint.
    - `applied` object
      - `filters` string[] — Names of the filters/parameters that were actually applied
      - `values` object — Map of applied filter name to the value that was applied
    - `available` object
      - `shared` object
        - `values` string[]
        - `description` string
        - `current` string, nullable
        - `applied` boolean
      - `tags` object — Advertised in the `available` catalog but not currently applied as a filter by the server.
        - `type` string
        - `description` string
        - `current` string, nullable
        - `applied` boolean
      - `minMessages` object — Advertised in the `available` catalog but not currently applied as a filter by the server.
        - `type` string
        - `description` string
        - `current` string, nullable
        - `applied` boolean
      - `search` object
        - `type` string
        - `description` string
        - `current` string, nullable
        - `applied` boolean
      - `pagination` object
        - `page` object
          - `type` string
          - `current` integer
          - `min` integer
          - `max` integer
          - `default` integer
          - `description` string
          - `applied` boolean
        - `limit` object
          - `type` string
          - `current` integer
          - `min` integer
          - `max` integer
          - `default` integer
          - `description` string
          - `applied` boolean
      - `sorting` object — Sort applied to the conversation list. Field set echoes back the original list-endpoint sort options even though this endpoint returns a single conversation.
        - `sortBy` object
          - `values` string[]
          - `default` string
          - `description` string
          - `current` string
          - `applied` boolean
        - `sortOrder` object
          - `values` string[]
          - `default` string
          - `description` string
          - `current` string
          - `applied` boolean
      - `dateFilters` object
        - `dateRange` object
          - `type` string
          - `description` string
          - `format` string
          - `current` object
            - `start` string, nullable
            - `end` string, nullable
          - `applied` boolean
      - `messageFilters` object
        - `messageType` object
          - `values` string[]
          - `description` string
          - `current` string, nullable
          - `applied` boolean
      - `sortingMessages` object — Sort applied to messages within the conversation (separate from the conversation-list `sorting` block).
        - `sortBy` object
          - `values` string[]
          - `default` string
          - `description` string
          - `current` string
        - `sortOrder` object
          - `values` string[]
          - `default` string
          - `description` string
          - `current` string
  - `meta` object
    - `requestId` string
    - `timestamp` string, date-time
    - `duration` integer — Server processing time in milliseconds
    - `conversationId` string, objectId
    - `messageCount` integer — Total number of messages in the conversation

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - No access to this conversation
- `404` — Conversation not found

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)