List ChatKit thread items

beta.chatkit.threads.list_items(thread_id, **kwargs) -> ConversationCursorPage<ChatKitThreadUserMessageItem { id, attachments, content, 5 more } | ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } | ChatKitWidgetItem { id, created_at, object, 3 more } | 3 more>

GET/chatkit/threads/{thread_id}/items

List items that belong to a ChatKit thread.

ParametersExpand Collapse

thread_id: String

after: String

List items created after this thread item ID. Defaults to null for the first page.

before: String

List items created before this thread item ID. Defaults to null for the newest results.

limit: Integer

Maximum number of thread items to return. Defaults to 20.

minimum0

maximum100

order: :asc | :desc

Sort order for results by creation time. Defaults to desc.

Accepts one of the following:

:asc

:desc

ReturnsExpand Collapse

ChatKitThreadUserMessageItem { id, attachments, content, 5 more } | ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } | ChatKitWidgetItem { id, created_at, object, 3 more } | 3 more

Accepts one of the following:

class ChatKitThreadUserMessageItem { id, attachments, content, 5 more }

User-authored messages within a thread.

id: String

Identifier of the thread item.

attachments: Array[ChatKitAttachment { id, mime_type, name, 2 more } ]

Attachments associated with the user message. Defaults to an empty list.

id: String

Identifier for the attachment.

mime_type: String

MIME type of the attachment.

name: String

Original display name for the attachment.

preview_url: String

Preview URL for rendering the attachment inline.

type: :image | :file

Attachment discriminator.

Accepts one of the following:

:image

:file

content: Array[{ text, type} | { text, type}]

Ordered content elements supplied by the user.

Accepts one of the following:

class InputText { text, type }

Text block that a user contributed to the thread.

text: String

Plain-text content supplied by the user.

type: :input_text

Type discriminator that is always input_text.

class QuotedText { text, type }

Quoted snippet that the user referenced in their message.

text: String

Quoted text content.

type: :quoted_text

Type discriminator that is always quoted_text.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

inference_options: { model, tool_choice}

Inference overrides applied to the message. Defaults to null when unset.

model: String

Model name that generated the response. Defaults to null when using the session default.

tool_choice: { id}

Preferred tool to invoke. Defaults to null when ChatKit should auto-select.

id: String

Identifier of the requested tool.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.user_message"

class ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more }

Assistant-authored message within a thread.

id: String

Identifier of the thread item.

content: Array[ChatKitResponseOutputText { annotations, text, type } ]

Ordered assistant response segments.

annotations: Array[{ source, type} | { source, type}]

Ordered list of annotations attached to the response text.

Accepts one of the following:

class File { source, type }

Annotation that references an uploaded file.

source: { filename, type}

File attachment referenced by the annotation.

filename: String

Filename referenced by the annotation.

type: :file

Type discriminator that is always file.

type: :file

Type discriminator that is always file for this annotation.

class URL { source, type }

Annotation that references a URL.

source: { type, url}

URL referenced by the annotation.

type: :url

Type discriminator that is always url.

url: String

URL referenced by the annotation.

type: :url

Type discriminator that is always url for this annotation.

text: String

Assistant generated text.

type: :output_text

Type discriminator that is always output_text.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.assistant_message"

Type discriminator that is always chatkit.assistant_message.

class ChatKitWidgetItem { id, created_at, object, 3 more }

Thread item that renders a widget payload.

id: String

Identifier of the thread item.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

thread_id: String

Identifier of the parent thread.

type: :"chatkit.widget"

Type discriminator that is always chatkit.widget.

class ChatKitClientToolCall { id, arguments, call_id, 7 more }

Record of a client side tool invocation initiated by the assistant.

id: String

Identifier of the thread item.

arguments: String

JSON-encoded arguments that were sent to the tool.

call_id: String

Identifier for the client tool call.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

name: String

Tool name that was invoked.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

output: String

JSON-encoded output captured from the tool. Defaults to null while execution is in progress.

status: :in_progress | :completed

Execution status for the tool call.

Accepts one of the following:

:in_progress

:completed

thread_id: String

Identifier of the parent thread.

type: :"chatkit.client_tool_call"

Type discriminator that is always chatkit.client_tool_call.

class ChatKitTask { id, created_at, heading, 5 more }

Task emitted by the workflow to show progress and status updates.

id: String

Identifier of the thread item.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

heading: String

Optional heading for the task. Defaults to null when not provided.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

summary: String

Optional summary that describes the task. Defaults to null when omitted.

task_type: :custom | :thought

Subtype for the task.

Accepts one of the following:

:custom

:thought

thread_id: String

Identifier of the parent thread.

type: :"chatkit.task"

Type discriminator that is always chatkit.task.

class ChatKitTaskGroup { id, created_at, object, 3 more }

Collection of workflow tasks grouped together in the thread.

id: String

Identifier of the thread item.

created_at: Integer

Unix timestamp (in seconds) for when the item was created.

object: :"chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

tasks: Array[{ heading, summary, type}]

Tasks included in the group.

heading: String

Optional heading for the grouped task. Defaults to null when not provided.

summary: String

Optional summary that describes the grouped task. Defaults to null when omitted.

type: :custom | :thought

Subtype for the grouped task.

Accepts one of the following:

:custom

:thought

thread_id: String

Identifier of the parent thread.

type: :"chatkit.task_group"

Type discriminator that is always chatkit.task_group.

List ChatKit thread items

require "openai"

openai = OpenAI::Client.new

page = openai.beta.chatkit.threads.list_items("cthr_123")

puts(page)

{
  "data": [
    {
      "id": "cthi_user_001",
      "object": "chatkit.thread_item",
      "type": "user_message",
      "content": [
        {
          "type": "input_text",
          "text": "I need help debugging an onboarding issue."
        }
      ],
      "attachments": []
    },
    {
      "id": "cthi_assistant_002",
      "object": "chatkit.thread_item",
      "type": "assistant_message",
      "content": [
        {
          "type": "output_text",
          "text": "Let's start by confirming the workflow version you deployed."
        }
      ]
    }
  ],
  "has_more": false,
  "object": "list"
}

Returns Examples

{
  "data": [
    {
      "id": "cthi_user_001",
      "object": "chatkit.thread_item",
      "type": "user_message",
      "content": [
        {
          "type": "input_text",
          "text": "I need help debugging an onboarding issue."
        }
      ],
      "attachments": []
    },
    {
      "id": "cthi_assistant_002",
      "object": "chatkit.thread_item",
      "type": "assistant_message",
      "content": [
        {
          "type": "output_text",
          "text": "Let's start by confirming the workflow version you deployed."
        }
      ]
    }
  ],
  "has_more": false,
  "object": "list"
}