OpenAI 列出 ChatKit 线程

2026-11-19 18:07 更新

get /chatkit/threads

列出 ChatKit 线程,支持分页及按用户筛选。

查询参数

  • after: optional string

列出此 ID 之后创建的记录。请求第一页时默认为 null。

  • before: optional string

列出此 ID 之前创建的记录。获取最新结果时默认为 null。

  • limit: optional integer

每页最多返回的线程数,默认为 20。

minimum: 0, maximum: 100

  • order: optional "asc" or "desc"

按创建时间排序,默认为 desc(降序)。asc 表示升序。

  • "asc"

  • "desc"

  • user: optional string

筛选属于指定用户标识符的线程。默认为 null,即按所有用户返回。

minLength: 1, maxLength: 512

返回值

  • data: array of ChatKitThread

线程列表。

  • id: string

线程的标识符。

  • created_at: integer

线程创建时的 Unix 时间戳,单位为秒。

format: unixtime

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

对象类型,固定为 chatkit.thread。

  • "chatkit.thread"

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

线程的当前状态。新建线程默认为 active。

  • Active object { type }

线程处于活动状态。

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

状态类型,固定为 active。

  • "active"

  • Locked object { reason, type }

线程已锁定,无法接收新输入。

  • reason: string or null

线程锁定的原因。没有记录原因时默认为 null。

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

状态类型,固定为 locked。

  • "locked"

  • Closed object { reason, type }

线程已关闭。

  • reason: string or null

线程关闭的原因。没有记录原因时默认为 null。

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

状态类型,固定为 closed。

  • "closed"

  • title: string or null

可供阅读的线程标题。尚未生成标题时默认为 null。

  • user: string

标识该线程所属终端用户的字符串。

  • first_id: string or null

列表中第一条记录的 ID。

  • has_more: boolean

是否还有更多记录。

  • last_id: string or null

列表中最后一条记录的 ID。

  • object: "list" (default: "list")

返回对象的类型,固定为 list。

  • "list"

请求示例

## 在服务端设置 OPENAI_API_KEY 环境变量。
## 可添加 limit、order 或 user 查询参数来控制分页和筛选范围。
curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \
  -H "OpenAI-Beta: chatkit_beta=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

响应示例

{
  "data": [
    {
      "id": "cthr_abc123",
      "object": "chatkit.thread",
      "title": "需升级处理的客户问题",
      "created_at": 1712345600,
      "status": {
        "type": "active"
      },
      "user": "user_123"
    },
    {
      "id": "cthr_def456",
      "object": "chatkit.thread",
      "title": "演示反馈",
      "created_at": 1712345600,
      "status": {
        "type": "active"
      },
      "user": "user_456"
    }
  ],
  "has_more": false,
  "object": "list",
  "first_id": "cthr_abc123",
  "last_id": "cthr_def456"
}

取得目标线程 ID 后,可获取 ChatKit 线程 查看该线程的当前状态。

以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号