文档中心

火山方舟

会话线程

查询线程详情

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

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

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

说明

线程信息是根据会话执行事件形成的当前视图：

created_at 表示首次观察到该线程的时间。

updated_at 表示最近一次状态变化时间。

stats 表示当前线程的累计运行时长、生命周期总时长和启动准备时长。

usage 表示当前线程运行期间累计的运行时长、模型 token 和服务端搜索请求统计。

鉴权

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

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

请求参数

Path 参数

session_id string 必选 | 会话 ID

thread_id string 必选 | 线程 ID

响应参数

agent_name string | 智能体名称

created_at string | 创建时间

id string | 线程 ID

parent_thread_id string / null | 父线程 ID

session_id string | 会话 ID

stats object | 时长统计

status string | 线程状态

type string | 对象类型

updated_at string | 更新时间

*usage object  |  用量统计
*当前线程运行期间累计的运行时长、模型 token 和服务端搜索请求统计。用量统计暂不可用时，服务端不返回该字段。
* 
* 
* 
* 
* 
* 

*active_seconds number  |  累计运行时长
*usage.active_seconds
*当前线程处于 running 状态的累计时长，单位为秒。

*cache_creation object  |  缓存创建统计
*usage.cache_creation
*当前线程的提示词缓存创建 token 统计。当前服务端不区分缓存有效期，两个字段均返回 0。
* 
* 

*ephemeral_1h_input_tokens integer  |  1 小时缓存输入 token 数
*usage.cache_creation.ephemeral_1h_input_tokens
*1 小时有效期提示词缓存的输入 token 数。当前固定返回 0。

*ephemeral_5m_input_tokens integer  |  5 分钟缓存输入 token 数
*usage.cache_creation.ephemeral_5m_input_tokens
*5 分钟有效期提示词缓存的输入 token 数。当前固定返回 0。

*cache_read_input_tokens integer  |  缓存读取 token 数
*usage.cache_read_input_tokens
*当前线程累计从提示词缓存读取的输入 token 数。

*input_tokens integer  |  输入 token 数
*usage.input_tokens
*当前线程内所有模型请求累计消耗的未缓存输入 token 数。

*output_tokens integer  |  输出 token 数
*usage.output_tokens
*当前线程内所有模型请求累计生成的输出 token 数。

*server_tool_use object  |  服务端工具用量
*usage.server_tool_use
*当前线程内服务端托管搜索工具累计发起的请求次数。
* 
* 
* 
* 

*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_search_requests integer  |  联网搜索请求次数
*usage.server_tool_use.web_search_requests
*服务端执行联网搜索的累计请求次数。

usage object | 用量统计

server_tool_use object | 服务端工具用量

查询会话线程详情

发起调试等同于请求真实调用，可能产生云产品费用，请谨慎操作！

Request

curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions/<SESSION_ID>/threads/<THREAD_ID>" \
  -H "Authorization: Bearer $ARK_API_KEY"

Response

{
  "id": "<THREAD_ID>",
  "session_id": "<SESSION_ID>",
  "status": "idle",
  "agent_name": "<AGENT_NAME>",
  "parent_thread_id": null,
  "stats": {
    "active_seconds": 68.206,
    "duration_seconds": 125.431,
    "startup_seconds": 2.75
  },
  "usage": {
    "active_seconds": 68.206,
    "cache_creation": {
      "ephemeral_1h_input_tokens": 0,
      "ephemeral_5m_input_tokens": 0
    },
    "cache_read_input_tokens": 126210,
    "input_tokens": 22,
    "output_tokens": 2373,
    "server_tool_use": {
      "web_fetch_requests": 0,
      "web_search_requests": 2,
      "general_search_requests": 1,
      "visual_search_requests": 0
    }
  },
  "created_at": "2026-07-15T08:30:14.900Z",
  "updated_at": "2026-07-15T08:30:19.220Z",
  "type": "session_thread"
}

最近更新时间：2026.10.28 19:53:17

这个页面对您有帮助吗？

有用

无用