Skip to content
Primary navigation

Suggested
API Dashboard
API Reference
Beta
ChatKit
Threads

List ChatKit thread items

client.beta.chatkit.threads.listItems(stringthreadID, ThreadListItemsParams { after, before, limit, order } query?, RequestOptionsoptions?): 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
threadID: string
query: ThreadListItemsParams { after, before, limit, order }
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?: number

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.

One of the following:
"asc"
"desc"
ReturnsExpand Collapse
Data = ChatKitThreadUserMessageItem { id, attachments, content, 5 more } | ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } | ChatKitWidgetItem { id, created_at, object, 3 more } | 3 more

User-authored messages within a thread.

One of the following:
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 | null

Preview URL for rendering the attachment inline.

type: "image" | "file"

Attachment discriminator.

One of the following:
"image"
"file"
content: Array<InputText { text, type } | QuotedText { text, type } >

Ordered content elements supplied by the user.

One of the following:
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.

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: number

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

inference_options: InferenceOptions | null

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

model: string | null

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

tool_choice: ToolChoice | null

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"
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<File { source, type } | URL { source, type } >

Ordered list of annotations attached to the response text.

One of the following:
File { source, type }

Annotation that references an uploaded file.

source: 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.

URL { source, type }

Annotation that references a URL.

source: 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: number

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.

ChatKitWidgetItem { id, created_at, object, 3 more }

Thread item that renders a widget payload.

id: string

Identifier of the thread item.

created_at: number

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.

widget: string

Serialized widget payload rendered in the UI.

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: number

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 | null

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.

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.

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: number

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

heading: string | null

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 | null

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

task_type: "custom" | "thought"

Subtype for the task.

One of the following:
"custom"
"thought"
thread_id: string

Identifier of the parent thread.

type: "chatkit.task"

Type discriminator that is always chatkit.task.

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: number

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

object: "chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

tasks: Array<Task>

Tasks included in the group.

heading: string | null

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

summary: string | null

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

type: "custom" | "thought"

Subtype for the grouped task.

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

import OpenAI from 'openai';

const client = new OpenAI();

// Automatically fetches more pages as needed.
for await (const thread of client.beta.chatkit.threads.listItems('cthr_123')) {
  console.log(thread);
}

{
  "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"
}