获取指定子 Agent 的单个 Turn,查看状态、时间边界、错误和 Token 用量。
接口
GET /agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}
成功返回 200,响应体是单个 Turn。查询不启动或恢复子 Agent,也不创建资源。
路径参数session_idstring (必选)Session ID,例如 sess_xxxsubagent_id string (必选)稳定的子 Agent ID,例如 subagent_xxxturn_id string (必选)公开 Turn ID,例如 turn_xxx路径上下级必须匹配。Turn 不属于该子 Agent 或该 Session 时不返回数据。 | 请求示例 |
响应字段usage 包含 input_tokens、input_tokens_details.cached_tokens、output_tokens、output_tokens_details.reasoning_tokens 和 total_tokens。相关计数不齐时,整个 usage 为 null。id string公开 Turn IDobject stringTurn 对象类型,固定为 agent.session.turnsession_id string所属 Sessionagent_id string执行 Agentsubagent_id string / null子 Agent Turn 为对应子 Agent IDstatus stringTurn 状态:in_progress、waiting、completed、failed、cancelledcreated_at integer创建时间,Unix 秒started_at/completed_at integer / null开始时间和完成时间,Unix 秒。未到边界时为 nullerror object / nullTurn 级错误。
属性 code string错误码message string错误说明object / nullToken 用量。
属性 input_tokens integer输入 Token 数input_tokens_details object输入 Token 明细。
属性 cached_tokens integer命中缓存的输入 Token 数integer输出 Token 数output_tokens_details object输出 Token 明细。
属性 reasoning_tokens integer推理 Token 数integer总 Token 数waiting 不是成功终态。completed、failed、cancelled 才是终态。SSE 的 turn.created 事件中可能出现 queued,持久 Turn 从 in_progress 开始。 | 响应示例 |
错误码
| HTTP 状态码 | 错误类型 / 错误码 | 解决方案 |
|---|---|---|
404 | not_found_error / not_found_error | 确认 Session、Subagent、Turn 存在且属于同一工作空间,并使用匹配的路径层级 |
502 | server_error / agents_api_upstream_unavailable | 稍后重试;持续失败时提交工单并提供响应头中的 x-request-id |