Skip to main content

查询会话状态

千问办公企业旗舰版开发者文档:查询会话状态。

认证方式见APP开发者文档 → 认证接入。
  • 模块:会话服务(session)
  • 接口:GET/api/openapi/app/v1/sessions/{session_id}

请求参数

参数位置类型必填说明
session_idpathstring是创建会话接口返回的会话 ID。

响应

HTTP说明
200请求成功
default错误响应。按 code 判断具体错误,不能仅依赖 HTTP 状态码,多种错误可能共用状态码。
媒体类型:application/json。

响应200 SessionDetail

字段类型必填约束契约说明
childrenarray<ChildRef>是最多 15 项此会话创建的子会话,最多 15 个;没有时为空数组。每个子项也是独立会话,可按其 ID 查询详情。
created_atstring是ISO 8601 时间字符串会话创建时间,ISO 8601,含微秒和时区,例如 2026-08-24T09:15:04.123456+00:00。
current_turnTurnRef / null是—当前执行中的回合,没有时为 null。等待用户回答的回合也算执行中,因此 action_required 时可非 null。用 turn_id 关联 Prompt 响应、事件和回合详情。回合切换时它与 status 可能短暂不同步,判断是否有回合可取消时优先参考 current_turn;持续不一致需要排查。
cursorinteger是format="int64"会话最新事件序号,可用于历史查询。0 表示没有可用游标,可能尚无事件或本次读取失败;此时保留已有位置,不用 0 覆盖。
end_reasonstring / null是—会话结束原因,未结束时为 null,仅 terminated 时设置。开放枚举,未知值按异常结束处理。
ended_atstring / null是ISO 8601 时间字符串会话结束时间;仍存活时为 null。ISO 8601,格式与 created_at 相同。
errorSessionError / null是—结构化失败信息,异常结束时返回;无失败时为 null。
modestring是—会话使用的能力档位。开放枚举,可用值通过运行档位列表查询。
multi_agentMultiAgentConfig是—此会话的子 Agent 配置。
namestring是—会话显示名称,未指定时从首条 Prompt 生成。
parent_session_idstring / null是—创建此会话的父会话 ID;顶层会话为 null。
pending_actionPendingAction / null是—等待用户处理的问题;仅 action_required 状态下非 null。包含完整问题和提交回答所需的 tool_call_id。
session_idstring是—创建接口返回的会话 ID。
statusstring是—当前会话状态,以此字段判断生命周期状态。
updated_atstring是ISO 8601 时间字符串会话记录最近更新时间,ISO 8601,格式与 created_at 相同。

响应200 ChildRef

字段类型必填约束契约说明
namestring是—子会话显示名称。
session_idstring是—子会话 ID,可用于查询完整详情。
statusstring是—子会话当前状态。

响应200 MultiAgentConfig

字段类型必填约束契约说明
child_modestring否—指定子会话的能力档位;省略时继承当前会话档位。
enabledboolean / null是—是否允许 Agent 创建子会话。每个子会话使用独立运行环境,会增加计算资源消耗;已创建的子会话列在会话详情的 children 中。

TurnRef

字段类型必填说明
started_atstring是回合开始时间,ISO 8601,含微秒和时区。尚未开始的排队 Prompt 不在此返回。
turn_idstring是当前回合 ID,用于查询回合详情及关联事件。

SessionError

字段类型必填说明
categorystring否错误分类:quota、auth、permission、rate_limit、model_unavailable、timeout、content_rejected、input_too_large、input_invalid、limit_reached、service_error、unknown;开放枚举。
codestring是机器可识别的错误码;未知值按一般失败处理。
messagestring是供展示和排查的错误文字,不作为程序分支条件。
remedystring否建议处理方式:retry、retry_after_backoff、switch_model、new_session、modify_input、reauthenticate、top_up_quota、contact_admin、refresh、report。按此字段决定下一步;未知值不盲目重试。
trace_idstring否服务端请求追踪标识,用于故障排查。

PendingAction

字段类型必填说明
asked_atstring是Agent 提问时间,ISO 8601,含微秒和时区。
questionsarray<Question>是待展示的问题数组;answers 按相同顺序提交。
tool_call_idstring是提交问题回答时原样传回的工具调用标识。

Question

字段类型必填说明
headerstring否可选的问题短标题。
multi_selectboolean是是否允许多选。每道题仍对应一个 answers 字符串;多选作为文本交给 Agent 解释,单选传选项 label。
optionsarray<QuestionOption>否可选项;省略或为空时允许自由文本回答。
questionstring是问题正文。

QuestionOption

字段类型必填说明
descriptionstring否选择此选项的补充说明。
labelstring是选项标识兼展示文字;回答时原样提交。

使用说明

创建会话绑定当前IAM用户;资源读取与变更按用户归属校验。写入发生超时或响应丢失时,不应假定服务端未接纳并盲目重复请求。