List ChatKit thread items

GET/chatkit/threads/{thread_id}/items

List items that belong to a ChatKit thread.

Path ParametersExpand Collapse

thread_id: string

Query ParametersExpand Collapse

after: optional string

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

before: optional string

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

limit: optional number

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

minimum0

maximum100

order: optional "asc" or "desc"

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

One of the following:

"asc"

"desc"

ReturnsExpand Collapse

ChatKitThreadItemList object { data, first_id, has_more, 2 more }

A paginated list of thread items rendered for the ChatKit API.

data: array of ChatKitThreadUserMessageItem { id, attachments, content, 5 more } or ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } or ChatKitWidgetItem { id, created_at, object, 3 more } or 3 more

A list of items

One of the following:

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

User-authored messages within a thread.

id: string

Identifier of the thread item.

attachments: array of 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 or null

Preview URL for rendering the attachment inline.

formaturi

type: "image" or "file"

Attachment discriminator.

One of the following:

"image"

"file"

content: array of object { text, type } or object { text, type }

Ordered content elements supplied by the user.

One of the following:

InputText object { 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 object { 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.

formatunixtime

inference_options: object { model, tool_choice } or null

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

model: string or null

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

tool_choice: object { id } or 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 object { id, content, created_at, 3 more }

Assistant-authored message within a thread.

id: string

Identifier of the thread item.

content: array of ChatKitResponseOutputText { annotations, text, type }

Ordered assistant response segments.

annotations: array of object { source, type } or object { source, type }

Ordered list of annotations attached to the response text.

One of the following:

File object { source, type }

Annotation that references an uploaded file.

source: object { 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 object { source, type }

Annotation that references a URL.

source: object { type, url }

URL referenced by the annotation.

type: "url"

Type discriminator that is always url.

url: string

URL referenced by the annotation.

formaturi

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.

formatunixtime

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 object { 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.

formatunixtime

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.

ChatKitClientToolCall object { 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.

formatunixtime

name: string

Tool name that was invoked.

object: "chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

output: string or null

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

status: "in_progress" or "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 object { 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.

formatunixtime

heading: string or 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 or null

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

task_type: "custom" or "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 object { 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.

formatunixtime

object: "chatkit.thread_item"

Type discriminator that is always chatkit.thread_item.

tasks: array of object { heading, summary, type }

Tasks included in the group.

heading: string or null

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

summary: string or null

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

type: "custom" or "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.

first_id: string or null

The ID of the first item in the list.

has_more: boolean

Whether there are more items available.

last_id: string or null

The ID of the last item in the list.

object: "list"

The type of object returned, must be list.