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

# Get Conversation

> Thread metadata plus one page of its message history. Paginate `items` with `limit` and `cursor`.

See [Read a conversation](/conversations/read-a-conversation).


## OpenAPI

````yaml get /v1/conversations/{conversation_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.trychannel3.com
    description: Production
security: []
paths:
  /v1/conversations/{conversation_id}:
    get:
      tags:
        - v1
      summary: Get Conversation
      description: >-
        Thread metadata plus one page of its message history. Paginate `items`
        with `limit` and `cursor`.
      operationId: get_conversation_v1_conversations__conversation_id__get
      parameters:
        - name: conversation_id
          in: path
          required: true
          schema:
            type: string
            title: Conversation Id
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 200
            minimum: 1
            default: 50
            title: Limit
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
        '400':
          description: Invalid cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationErrorBody'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationErrorBody'
        '402':
          description: Payment required
          content:
            application/json:
              examples:
                credits_exhausted:
                  summary: API key out of credits
                  value:
                    detail: >-
                      You have used all of your free credits. Add a payment
                      method to continue.
                mpp_challenge:
                  summary: MPP Tempo payment required
                  value:
                    detail: >-
                      Payment required. Satisfy the MPP Tempo challenge in
                      WWW-Authenticate.
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationErrorBody'
        '422':
          description: Request validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationErrorBody'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationErrorBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationErrorBody'
      security:
        - APIKeyHeader: []
        - Bearer: []
      x-codeSamples:
        - lang: JavaScript
          source: >-
            import Channel3 from '@channel3/sdk';


            const client = new Channel3({
              apiKey: process.env['CHANNEL3_API_KEY'], // This is the default and can be omitted
            });


            const conversationDetail = await
            client.conversations.retrieve('conversation_id');


            console.log(conversationDetail.id);
        - lang: Python
          source: |-
            import os
            from channel3_sdk import Channel3

            client = Channel3(
                api_key=os.environ.get("CHANNEL3_API_KEY"),  # This is the default and can be omitted
            )
            conversation_detail = client.conversations.retrieve(
                conversation_id="conversation_id",
            )
            print(conversation_detail.id)
        - lang: Go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/channel3-ai/sdk-go\"\n\t\"github.com/channel3-ai/sdk-go/option\"\n)\n\nfunc main() {\n\tclient := channel3go.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tconversationDetail, err := client.Conversations.Get(\n\t\tcontext.TODO(),\n\t\t\"conversation_id\",\n\t\tchannel3go.ConversationGetParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", conversationDetail.ID)\n}\n"
        - lang: CLI
          source: |-
            channel3 conversations retrieve \
              --api-key 'My API Key' \
              --conversation-id conversation_id
components:
  schemas:
    ConversationDetail:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: integer
          title: Created At
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
        context:
          anyOf:
            - $ref: '#/components/schemas/ConversationContext'
            - type: 'null'
        items:
          items:
            oneOf:
              - $ref: '#/components/schemas/UserMessage'
              - $ref: '#/components/schemas/AssistantMessage'
            discriminator:
              propertyName: role
              mapping:
                assistant:
                  $ref: '#/components/schemas/AssistantMessage'
                user:
                  $ref: '#/components/schemas/UserMessage'
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Pass as ``cursor`` to fetch the next page. Null when no more items.
        has_more:
          type: boolean
          title: Has More
          default: false
      type: object
      required:
        - id
        - created_at
        - items
      title: ConversationDetail
      description: Thread metadata plus one page of its message history.
    ConversationErrorBody:
      properties:
        error:
          $ref: '#/components/schemas/ConversationError'
      type: object
      required:
        - error
      title: ConversationErrorBody
      description: Error envelope for all non-2xx ``/v1/conversations`` responses.
    ErrorResponse:
      properties:
        detail:
          anyOf:
            - type: string
            - items:
                additionalProperties: true
                type: object
              type: array
          title: Detail
      type: object
      required:
        - detail
      title: ErrorResponse
    ConversationContext:
      properties:
        user_context:
          anyOf:
            - type: string
            - type: 'null'
          title: User Context
          description: Who the conversation is with (profile, preferences, session facts).
        application_context:
          anyOf:
            - type: string
            - type: 'null'
          title: Application Context
          description: What platform or surface is hosting this conversation.
      type: object
      title: ConversationContext
      description: Partner-supplied context pinned to the top of a conversation thread.
    UserMessage:
      properties:
        role:
          type: string
          const: user
          title: Role
          default: user
        parts:
          items:
            oneOf:
              - $ref: '#/components/schemas/TextPart'
              - $ref: '#/components/schemas/ImagePart'
            discriminator:
              propertyName: type
              mapping:
                image:
                  $ref: '#/components/schemas/ImagePart'
                text:
                  $ref: '#/components/schemas/TextPart'
          type: array
          title: Parts
      type: object
      title: UserMessage
    AssistantMessage:
      properties:
        role:
          type: string
          const: assistant
          title: Role
          default: assistant
        parts:
          items:
            oneOf:
              - $ref: '#/components/schemas/TextPart'
              - $ref: '#/components/schemas/ToolPart'
            discriminator:
              propertyName: type
              mapping:
                text:
                  $ref: '#/components/schemas/TextPart'
                tool:
                  $ref: '#/components/schemas/ToolPart'
          type: array
          title: Parts
        suggestions:
          items:
            type: string
          type: array
          title: Suggestions
          description: Tap-ready follow-up messages offered after this reply.
      type: object
      title: AssistantMessage
    ConversationError:
      properties:
        code:
          $ref: '#/components/schemas/TurnErrorCode'
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ConversationError
    TextPart:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
        text:
          type: string
          title: Text
      type: object
      required:
        - text
      title: TextPart
    ImagePart:
      properties:
        type:
          type: string
          const: image
          title: Type
          default: image
        url:
          type: string
          title: Url
      type: object
      required:
        - url
      title: ImagePart
      description: An image by URL. ``data:`` URIs are uploaded and rewritten server-side.
    ToolPart:
      properties:
        type:
          type: string
          const: tool
          title: Type
          default: tool
        tool_call_id:
          type: string
          title: Tool Call Id
        tool_name:
          type: string
          title: Tool Name
        input:
          anyOf:
            - $ref: '#/components/schemas/SearchProductsInput'
            - $ref: '#/components/schemas/ProductIdsInput'
          title: Input
        output:
          anyOf:
            - $ref: '#/components/schemas/CatalogDisplayPayload'
            - $ref: '#/components/schemas/CatalogToolError'
            - type: 'null'
          title: Output
      type: object
      required:
        - tool_call_id
        - tool_name
      title: ToolPart
      description: One catalog tool call and its display payload from an assistant turn.
    TurnErrorCode:
      type: string
      enum:
        - invalid_request
        - unauthorized
        - insufficient_credits
        - conversation_not_found
        - turn_conflict
        - rate_limited
        - model_unavailable
        - token_not_found
        - service_unavailable
        - internal
      title: TurnErrorCode
    SearchProductsInput:
      properties:
        query:
          type: string
          title: Query
      type: object
      required:
        - query
      title: SearchProductsInput
    ProductIdsInput:
      properties:
        product_ids:
          items:
            type: string
          type: array
          title: Product Ids
      type: object
      title: ProductIdsInput
    CatalogDisplayPayload:
      properties:
        products:
          items:
            $ref: '#/components/schemas/Product'
          type: array
          title: Products
        next_page_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Page Token
      additionalProperties: true
      type: object
      title: CatalogDisplayPayload
      description: >-
        Client-facing catalog tool result shown on the stream and on
        ``ToolPart``.
    CatalogToolError:
      properties:
        error:
          type: string
          title: Error
        is_error:
          type: boolean
          const: true
          title: Is Error
          default: true
        products:
          items:
            $ref: '#/components/schemas/Product'
          type: array
          title: Products
      type: object
      required:
        - error
      title: CatalogToolError
    Product:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        brands:
          items:
            $ref: '#/components/schemas/ProductBrand'
          type: array
          title: Brands
          description: Ordered list of brands.
        images:
          items:
            $ref: '#/components/schemas/ProductImage'
          type: array
          title: Images
          default: []
        category:
          anyOf:
            - $ref: '#/components/schemas/CategorySummary'
            - type: 'null'
          description: >-
            The single category this product belongs to, as a structured
            `CategorySummary` (slug, title, path, has_children).
        gender:
          anyOf:
            - $ref: '#/components/schemas/Gender'
            - type: 'null'
        age:
          anyOf:
            - $ref: '#/components/schemas/Age'
            - type: 'null'
          description: >-
            Target age group. Age-agnostic products are typically returned as
            'adult'.
        materials:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Materials
        key_features:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Key Features
        offers:
          items:
            $ref: '#/components/schemas/ProductOffer'
          type: array
          title: Offers
          description: All merchant offers for this product in the requested locale.
        variants:
          anyOf:
            - $ref: '#/components/schemas/Variants'
            - type: 'null'
          description: >-
            Variant interaction state — options, selected. Absent when the
            product has no variations.
        structured_attributes:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Structured Attributes
          description: >-
            Structured attributes extracted for this product, keyed by attribute
            handle (e.g. 'color', 'material'). Values are the canonical allowed
            values for that handle.
      type: object
      required:
        - id
        - title
      title: Product
      description: Product with detailed information.
    ProductBrand:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
      type: object
      required:
        - id
        - name
      title: ProductBrand
    ProductImage:
      properties:
        url:
          type: string
          title: Url
        cleaned_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Cleaned Url
          description: >-
            Background-removed square image on Channel3 CDN when available. Use
            for product grids; ``url`` is the regular hosted shot.
        is_main_image:
          type: boolean
          title: Is Main Image
          default: false
        shot_type:
          anyOf:
            - $ref: '#/components/schemas/ApiProductImageType'
            - type: 'null'
        alt_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Alt Text
      type: object
      required:
        - url
      title: ProductImage
      description: Product image with metadata.
    CategorySummary:
      properties:
        slug:
          type: string
          title: Slug
          description: URL-friendly slug (e.g. 'sofas')
        title:
          type: string
          title: Title
          description: Human-readable category title
        path:
          items:
            $ref: '#/components/schemas/CategoryRef'
          type: array
          title: Path
          description: >-
            Hierarchical path as a structured list, root first; the last entry
            is this category itself
        has_children:
          type: boolean
          title: Has Children
          description: Whether this category has subcategories
      type: object
      required:
        - slug
        - title
        - has_children
      title: CategorySummary
      description: Lean category representation used in search hits and list rows.
    Gender:
      type: string
      enum:
        - male
        - female
      title: Gender
      description: >-
        Product gender. 'unisex' is deprecated: coerced to None on input, never
        emitted.
    Age:
      type: string
      enum:
        - newborn
        - infant
        - toddler
        - kids
        - adult
      title: Age
    ProductOffer:
      properties:
        url:
          type: string
          title: Url
        domain:
          type: string
          title: Domain
        price:
          $ref: '#/components/schemas/Price'
        availability:
          $ref: '#/components/schemas/OfferAvailabilityStatus'
        condition:
          anyOf:
            - $ref: '#/components/schemas/Condition'
            - type: 'null'
          description: >-
            Condition of this merchant offer (new or used). Null when condition
            is unknown.
        max_commission_rate:
          type: number
          title: Max Commission Rate
          description: >-
            The maximum commission rate for the merchant, as a decimal fraction:
            0 is no commission, 0.5 is 50% commission. 'Max' because the actual
            commission rate may be lower due to vendor-specific affiliate rules.
          default: 0
        dimensions:
          anyOf:
            - $ref: '#/components/schemas/Dimensions'
            - type: 'null'
          description: Physical dimensions of this offer. Null when unknown.
      type: object
      required:
        - url
        - domain
        - price
        - availability
      title: ProductOffer
    Variants:
      properties:
        options:
          items:
            $ref: '#/components/schemas/VariantOption'
          type: array
          title: Options
        selected:
          items:
            $ref: '#/components/schemas/SelectedOption'
          type: array
          title: Selected
      type: object
      required:
        - options
        - selected
      title: Variants
      description: |-
        Wrapper for variant-interaction state on a Product.

        Holds `options` and `selected`. `options` represent all of the
        configuration options for the product. `selected` represents the
        currently selected option values.
    ApiProductImageType:
      type: string
      enum:
        - hero
        - lifestyle
        - on_model
        - detail
        - scale_reference
        - angle_view
        - flat_lay
        - in_use
        - packaging
        - size_chart
        - product_information
        - merchant_information
      title: ApiProductImageType
      description: Product image type classification for API responses.
    CategoryRef:
      properties:
        slug:
          type: string
          title: Slug
          description: URL-friendly slug (e.g. 'sofas')
        title:
          type: string
          title: Title
          description: Human-readable category title
      type: object
      required:
        - slug
        - title
      title: CategoryRef
      description: Lean reference to a category, used in path and children arrays.
    Price:
      properties:
        price:
          type: number
          title: Price
          description: The current price of the product, including any discounts.
        compare_at_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Compare At Price
          description: The original price of the product before any discounts.
        currency:
          type: string
          title: Currency
          description: The currency code of the product, like USD, EUR, GBP, etc.
      type: object
      required:
        - price
        - currency
      title: Price
    OfferAvailabilityStatus:
      type: string
      enum:
        - InStock
        - OutOfStock
      title: OfferAvailabilityStatus
      description: |-
        The two availability values the public API emits on offers.

        Internal ``AvailabilityStatus`` values are collapsed to these via
        ``AvailabilityStatus.to_api()``.
    Condition:
      type: string
      enum:
        - new
        - used
      title: Condition
      description: >-
        Offer condition. 'refurbished' is deprecated: rejected as a filter
        value,

        coerced to None on responses.
    Dimensions:
      properties:
        length:
          anyOf:
            - $ref: '#/components/schemas/LengthDimension'
            - type: 'null'
        width:
          anyOf:
            - $ref: '#/components/schemas/LengthDimension'
            - type: 'null'
        height:
          anyOf:
            - $ref: '#/components/schemas/LengthDimension'
            - type: 'null'
        weight:
          anyOf:
            - $ref: '#/components/schemas/WeightDimension'
            - type: 'null'
      type: object
      title: Dimensions
      description: >-
        Physical dimensions of a product offer. Members are null when unknown.


        Values are standardized to the supported unit set; a merchant-stated
        value

        whose unit is not one of those units is omitted rather than shown.
    VariantOption:
      properties:
        name:
          type: string
          title: Name
          description: The name of the option (e.g. 'Color', 'Size')
        values:
          items:
            $ref: '#/components/schemas/OptionValue'
          type: array
          title: Values
          description: The values of the option (e.g. ['Blue', 'Red', 'Green'])
      type: object
      required:
        - name
        - values
      title: VariantOption
      description: One dimension of a product family (e.g. 'Color', 'Size').
    SelectedOption:
      properties:
        name:
          type: string
          title: Name
          description: The name of the selected option (e.g. 'Color', 'Size')
        label:
          type: string
          title: Label
          description: The display value of the selected option (e.g. 'Blue', 'XL')
      type: object
      required:
        - name
        - label
      title: SelectedOption
      description: One effective selection on a product, post server-side relaxation.
    LengthDimension:
      properties:
        number:
          type: number
          title: Number
        unit:
          $ref: '#/components/schemas/LengthUnit'
          description: >-
            The unit from the request's dimension filters when one was given
            (the value is converted to it); otherwise the unit the merchant
            stated.
      type: object
      required:
        - number
        - unit
      title: LengthDimension
      description: A length measurement, in one of the supported length units.
    WeightDimension:
      properties:
        number:
          type: number
          title: Number
        unit:
          $ref: '#/components/schemas/WeightUnit'
          description: >-
            The unit from the request's dimension filters when one was given
            (the value is converted to it); otherwise the unit the merchant
            stated.
      type: object
      required:
        - number
        - unit
      title: WeightDimension
      description: A weight measurement, in one of the supported weight units.
    OptionValue:
      properties:
        label:
          type: string
          title: Label
          description: The display value of the option value (e.g. 'Blue')
        exists:
          type: boolean
          title: Exists
          description: >-
            Whether the option value exists on the product, or is a
            configuration only present on another variant of the same product.
            For example, a shirt that comes in multiple colors, but only one
            color is available in Size XL.
        available:
          anyOf:
            - $ref: '#/components/schemas/OfferAvailabilityStatus'
            - type: 'null'
          description: >-
            The availability status of the option value. None when returned on
            search results, hydrated only on get product detail requests.
        thumbnail_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Thumbnail Url
          description: >-
            For options that reference different products, this is the URL of
            the thumbnail image for the option value. E.g., a shoe that comes in
            multiple colors will have an OptionValue for each color with a
            thumbnail_url set.
        product_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Id
          description: >-
            The product id that represents this value. Variants that point to
            different products will have this field set, as well as
            thumbnail_url for displaying selector icons.
      type: object
      required:
        - label
        - exists
      title: OptionValue
      description: One value of one variant option (e.g. 'Blue' under 'Color')
    LengthUnit:
      type: string
      enum:
        - mm
        - cm
        - m
        - in
        - ft
      title: LengthUnit
    WeightUnit:
      type: string
      enum:
        - mg
        - g
        - kg
        - oz
        - lb
      title: WeightUnit
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
    Bearer:
      type: http
      scheme: bearer
      x-fern-bearer:
        name: token
        env: CHANNEL3_TOKEN

````