面向 AI 助手:本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/get-thread-api.md,全部文档索引见 https://ark.volcengine.com/llms.txt。

查询线程详情

GET https://ark.cn-beijing.volces.com/api/v3/sessions/{session_id}/threads/{thread_id}

查询指定线程的当前状态、关联智能体和主子关系。已知 thread_id 时使用本接口。

查看全部线程请使用 查询线程列表;排查执行过程请使用 获取线程事件列表 。

鉴权#

本接口支持鉴权方式如下,详情请参见 Base URL 及鉴权。

  • API Key 鉴权,请在 API Key 管理 页面,获取长效 API Key。

请求参数#

Path 参数#

session_id string 必选  |  会话 ID

会话 ID,形如 sesn-...

thread_id string 必选  |  线程 ID

线程 ID,形如 sthr-...

响应参数#

agent_name string  |  智能体名称

线程关联的智能体名称

created_at string  |  创建时间

服务端创建线程的时间,格式为 RFC 3339。对于历史会话,该字段表示平台首次从已有事件中识别出该线程的时间。

id string  |  线程 ID

线程唯一标识符,形如 sthr-...

parent_thread_id string / null  |  父线程 ID

子线程的父线程 ID;主线程不返回该字段。

session_id string  |  会话 ID

所属会话 ID,形如 sesn-...

status string  |  线程状态

线程状态:

可继续处理的状态:

  • running:智能体正在处理当前工作
  • idle:当前工作已暂停或结束,可以继续向该线程派发任务

重试或终态:

  • rescheduling:正在从临时错误中自动恢复
  • archived:会话归档后,其子线程进入该状态;不能再接收任务,但仍可查询
  • terminated:线程已终止,不能再接收任何输入;历史协作模式的会话按事件还原线程时会出现该状态
  • unknown:当前事件不足以确定线程状态,需要结合线程事件继续排查
type string  |  对象类型

对象类型,固定为 session_thread

updated_at string  |  更新时间

线程信息最近更新时间,采用 RFC 3339 格式。

stats object  |  线程时长统计

Thread 的运行时长统计。

active_seconds number  |  活跃时长

stats.active_seconds

Thread 实际处于运行状态的累计秒数。每次 Thread 从 running 回到 idle 或 terminated,系统才把这次运行的时长累加进去;Thread 当前还在运行的时间暂不计入。

duration_seconds number  |  总时长

stats.duration_seconds

Thread 从创建到当前或终止时的总时长,单位为秒。

startup_seconds number  |  启动时长

stats.startup_seconds

会话主线程从创建到首次进入 running 的准备时长,单位为秒;子 Agent 线程返回 0。

usage object  |  线程用量

Thread 累计的模型和服务端工具用量。

active_seconds number  |  活跃时长

usage.active_seconds

Thread 实际处于运行状态的累计秒数。每次 Thread 从 running 回到 idle 或 terminated,系统才把这次运行的时长累加进去;Thread 当前还在运行的时间暂不计入。

cache_read_input_tokens integer  |  缓存读取 token 数

usage.cache_read_input_tokens

Thread 累计从提示词缓存读取的输入 token 数。

input_tokens integer  |  输入 token 数

usage.input_tokens

Thread 内所有模型请求累计消耗的输入 token 总数。

output_tokens integer  |  输出 token 数

usage.output_tokens

Thread 内所有模型请求累计生成的输出 token 总数。

server_tool_use object  |  服务端工具用量

usage.server_tool_use

Thread 累计调用服务端工具的次数。

general_search_requests integer  |  通用搜索次数

usage.server_tool_use.general_search_requests

服务端执行通用搜索的累计请求次数。

visual_search_requests integer  |  视觉搜索次数

usage.server_tool_use.visual_search_requests

服务端执行视觉搜索的累计请求次数。

web_fetch_requests integer  |  网页读取次数

usage.server_tool_use.web_fetch_requests

web_fetch 工具调用次数。

web_search_requests integer  |  网页搜索次数

usage.server_tool_use.web_search_requests

web_search 工具调用次数。