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

# Get a conversation with messages

> Retrieve a conversation and all its messages by thread ID.

The conversation must belong to the authenticated user's organization.

**Stream status values:**
- `in_progress`: Response is currently being generated
- `completed`: Response generation finished successfully
- `stopped`: Response generation was manually stopped
- `error`: Response generation encountered an error
- `timeout`: Response generation timed out
- `null`: No active stream




## OpenAPI

````yaml /openapi.yaml get /getConversation
openapi: 3.1.0
info:
  title: AsterAgents API
  version: 1.0.0
  description: >
    API for AsterAgents platform operations.


    - **Admin endpoints** (`/admin/*`) require organization admin privileges
    (`org:admin` role)

    - **Agent endpoints** (`/agents`) require agent management permissions or
    `org:admin` role

    - **Knowledge base endpoints** (`/kb/*`) require standard authentication

    - **Skills endpoints** (`/skills/*`) require standard authentication

    - **File endpoints** (`/upload/*`, `/kb/files`, `/skills/files`) require
    standard authentication
  contact:
    name: AsterAgents Support
    url: https://asteragents.com/support
servers:
  - url: https://asteragents.com/api
    description: Production
  - url: http://localhost:3000/api
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Users
    description: Manage active organization users
  - name: Invitations
    description: Manage organization invitations
  - name: Files
    description: Upload and manage files
  - name: Knowledge Bases
    description: Manage knowledge bases and their files
  - name: Knowledge Base Management
    description: Create, update, and delete knowledge bases
  - name: Agents
    description: Create, update, and delete agents
  - name: Agent Tags
    description: Organize agents with tags
  - name: Tools
    description: Discover the tool catalog available to your organization
  - name: Skills
    description: Manage agent skills
  - name: Skill Files
    description: Manage bundled files for skills
  - name: Conversations
    description: Invoke agents and retrieve conversation history and messages
  - name: Scheduled Tasks
    description: Schedule agents to run automatically on a cron schedule
paths:
  /getConversation:
    get:
      tags:
        - Conversations
      summary: Get a conversation with messages
      description: |
        Retrieve a conversation and all its messages by thread ID.

        The conversation must belong to the authenticated user's organization.

        **Stream status values:**
        - `in_progress`: Response is currently being generated
        - `completed`: Response generation finished successfully
        - `stopped`: Response generation was manually stopped
        - `error`: Response generation encountered an error
        - `timeout`: Response generation timed out
        - `null`: No active stream
      operationId: getConversation
      parameters:
        - name: threadId
          in: query
          required: true
          description: The UUID of the conversation thread
          schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Successfully retrieved conversation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationWithMessages'
              examples:
                active:
                  summary: Active conversation with messages
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    agentId: 123
                    userId: user_2ABC123DEF
                    organizationId: org_xxx
                    name: Help with quarterly report
                    upstreamConversationId: null
                    renderedSystemPrompt: You are a helpful assistant...
                    streamStatus: completed
                    createdAt: '2024-01-15T10:30:00.000Z'
                    updatedAt: '2024-01-15T10:35:00.000Z'
                    deletedAt: null
                    messages:
                      - id: 660e8400-e29b-41d4-a716-446655440001
                        role: user
                        parts:
                          - type: text
                            text: Can you help me analyze this data?
                      - id: 660e8400-e29b-41d4-a716-446655440002
                        role: assistant
                        parts:
                          - type: text
                            text: >-
                              Of course! I'd be happy to help you analyze the
                              data.
                deleted:
                  summary: Soft-deleted conversation
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    agentId: 123
                    userId: user_2ABC123DEF
                    organizationId: org_xxx
                    name: Old conversation
                    isDeleted: true
                    deletedAt: '2024-01-20T15:00:00.000Z'
        '400':
          description: Bad request - missing threadId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: threadId is required
        '404':
          description: Conversation not found or doesn't belong to your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Conversation not found
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Method not allowed
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ConversationWithMessages:
      type: object
      required:
        - id
        - agentId
        - userId
        - createdAt
        - updatedAt
        - messages
      properties:
        id:
          type: string
          format: uuid
          description: Unique conversation identifier
          example: 550e8400-e29b-41d4-a716-446655440000
        agentId:
          type: integer
          description: ID of the agent this conversation is with
          example: 123
        userId:
          type: string
          description: Clerk user ID of the conversation owner
          example: user_2ABC123DEF
        organizationId:
          type: string
          nullable: true
          description: Organization the conversation belongs to
          example: org_xxx
        name:
          type: string
          nullable: true
          description: Conversation name/title (auto-generated or user-defined)
          example: Help with quarterly report
        upstreamConversationId:
          type: string
          format: uuid
          nullable: true
          description: Parent conversation ID for branched conversations
          example: null
        renderedSystemPrompt:
          type: string
          nullable: true
          description: The system prompt used for this conversation (for audit)
          example: You are a helpful assistant...
        streamStatus:
          type: string
          nullable: true
          description: Current streaming status
          enum:
            - in_progress
            - completed
            - stopped
            - error
            - timeout
          example: completed
        createdAt:
          type: string
          format: date-time
          description: When the conversation was created
          example: '2024-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: When the conversation was last updated
          example: '2024-01-15T10:35:00.000Z'
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: When the conversation was soft-deleted (null if active)
          example: null
        isDeleted:
          type: boolean
          description: Present and true if conversation was soft-deleted
          example: false
        messages:
          type: array
          description: All messages in the conversation, ordered by creation time
          items:
            $ref: '#/components/schemas/ConversationMessage'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Bad Request
        details:
          type: array
          items:
            type: object
            additionalProperties: true
    ConversationMessage:
      type: object
      required:
        - id
        - role
        - parts
      properties:
        id:
          type: string
          format: uuid
          description: Unique message identifier
          example: 660e8400-e29b-41d4-a716-446655440001
        role:
          type: string
          description: Message role
          enum:
            - user
            - assistant
            - system
          example: user
        parts:
          type: array
          description: Message content parts (text, tool calls, step markers, files).
          items:
            $ref: '#/components/schemas/MessagePart'
        usage:
          type: object
          description: Per-message token usage (assistant messages only).
          properties:
            inputTokens:
              type: integer
            outputTokens:
              type: integer
            totalTokens:
              type: integer
            cachedInputTokens:
              type: integer
            reasoningTokens:
              type: integer
        finishReason:
          type: string
          description: >-
            Why generation stopped (assistant messages only), e.g. "stop",
            "tool-calls", "length".
          example: stop
    MessagePart:
      type: object
      description: >
        A single part of a message. The `type` field discriminates the shape.

        Tool calls use the AI SDK v5 format: the type is `tool-<toolName>`

        (e.g. `tool-search_knowledge_base`) — NOT a static `tool-invocation`/

        `tool-result`. The same part carries both the call `input` and, once the

        tool returns, the `output` (with `state` advancing to
        `output-available`).
      required:
        - type
      properties:
        type:
          type: string
          description: |
            Part type. One of `text`, `step-start`, `file`, or a dynamic
            `tool-<toolName>` value for tool calls.
          example: tool-search_knowledge_base
        text:
          type: string
          description: >-
            Text content (for `text` parts). May contain citation markdown links
            `[label](cite:<fileId>)` that resolve to a KB file id found in a
            tool part's `output`.
          example: Q3 revenue was $4,812,003. [Fact Sheet](cite:38437)
        toolCallId:
          type: string
          description: Tool call id (for `tool-<toolName>` parts).
          example: call_aquVL0uiP6lBqaofHke9Gaa5
        state:
          type: string
          description: Tool call lifecycle state (for `tool-<toolName>` parts).
          example: output-available
        input:
          type: object
          description: >-
            The arguments the model passed to the tool (for `tool-<toolName>`
            parts).
        output:
          type: object
          description: >-
            The tool's return value (for `tool-<toolName>` parts), typically `{
            status, content }`.
        file:
          type: object
          description: File attachment details (for `file` parts).
          properties:
            name:
              type: string
            contentType:
              type: string
            url:
              type: string
  responses:
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal Server Error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT token from Clerk authentication.

        Must be from a user with `org:admin` role.

````