Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

List ChatKit threads

GET
/chatkit/threads

List ChatKit threads with optional pagination and user filters.

Query Parameters
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 integer

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"
user: optional string

Filter threads that belong to this user identifier. Defaults to null to return all users.

minLength1
maxLength512
Returns
data: array of ChatKitThread { id, created_at, object, 3 more }

A list of items

id: string

Identifier of the thread.

created_at: integer

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

formatunixtime
object: "chatkit.thread" (default: "chatkit.thread")

Type discriminator that is always chatkit.thread.

status: Active { type } or Locked { reason, type } or Closed { reason, type }

Current status for the thread. Defaults to active for newly created threads.

One of the following:
Active object { type }

Indicates that a thread is active.

type: "active" (default: "active")

Status discriminator that is always active.

Locked object { reason, type }

Indicates that a thread is locked and cannot accept new input.

reason: string or null

Reason that the thread was locked. Defaults to null when no reason is recorded.

type: "locked" (default: "locked")

Status discriminator that is always locked.

Closed object { reason, type }

Indicates that a thread has been closed.

reason: string or null

Reason that the thread was closed. Defaults to null when no reason is recorded.

type: "closed" (default: "closed")

Status discriminator that is always closed.

title: string or null

Optional human-readable title for the thread. Defaults to null when no title has been generated.

user: string

Free-form string that identifies your end user who owns the thread.

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" (default: "list")

The type of object returned, must be list.

List ChatKit threads

curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \
  -H "OpenAI-Beta: chatkit_beta=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"
Response example
{
  "data": [
    {
      "id": "cthr_abc123",
      "object": "chatkit.thread",
      "title": "Customer escalation",
      "created_at": 1712345600,
      "status": {
        "type": "active"
      },
      "user": "user_123"
    },
    {
      "id": "cthr_def456",
      "object": "chatkit.thread",
      "title": "Demo feedback",
      "created_at": 1712345600,
      "status": {
        "type": "active"
      },
      "user": "user_456"
    }
  ],
  "has_more": false,
  "object": "list",
  "first_id": "cthr_abc123",
  "last_id": "cthr_def456"
}
Returns Examples
Response example
{
  "data": [
    {
      "id": "cthr_abc123",
      "object": "chatkit.thread",
      "title": "Customer escalation",
      "created_at": 1712345600,
      "status": {
        "type": "active"
      },
      "user": "user_123"
    },
    {
      "id": "cthr_def456",
      "object": "chatkit.thread",
      "title": "Demo feedback",
      "created_at": 1712345600,
      "status": {
        "type": "active"
      },
      "user": "user_456"
    }
  ],
  "has_more": false,
  "object": "list",
  "first_id": "cthr_abc123",
  "last_id": "cthr_def456"
}