OpenAI 列出会话轮次
get /agents/sessions/{session_id}/turns
按创建时间和轮次 ID 列出轮次。在指定排序下,游标 after 对应的轮次不会包含在返回结果中。参见会话轮次。
路径参数
session_id: string
会话 ID。
minLength: 0, maxLength: 1048576
查询参数
after: optional string
按选定顺序返回此资源 ID 之后的资源。
minLength: 0, maxLength: 1048576
limit: optional integer (default: 20)
返回资源的最大数量,范围为 1 至 100,默认为 20。
format: int64, minimum: 1, maximum: 100
order: optional "asc" or "desc" (default: "desc")
返回资源的排序方式,默认为 desc。
"asc"
按升序返回资源。
"desc"
按降序返回资源。
返回值
data: array of Turn
本页返回的资源,按指定顺序排列。
minItems: 0, maxItems: 2000
id: string
轮次 ID。
minLength: 0
agent_id: string
执行本轮的智能体 ID。
minLength: 0
completed_at: integer or null
轮次进入终态的 Unix 时间戳,单位为秒。
format: int64
created_at: integer
用于按创建时间排序的 Unix 时间戳,单位为秒。子智能体轮次优先使用开始时间,其次使用完成时间,前两者均不可用时使用子智能体打开的时间。
format: int64
error: SessionTurnError or null
可向客户显示的错误。仅轮次失败时为非空值。
code: "context_length_exceeded" or "max_output_tokens" or "usage_limit_exceeded" or 21 more
稳定的、可供程序识别的失败类别。
"context_length_exceeded"
请求超出模型的上下文窗口。
"max_output_tokens"
模型完成响应之前已达到输出词元上限。
"usage_limit_exceeded"
组织已达到用量、套餐或计费限制。
"api_key_spend_limit_exceeded"
API 密钥已达到强制支出上限。
"project_spend_limit_exceeded"
项目已达到强制支出上限。
"organization_spend_limit_exceeded"
组织已达到强制支出上限。
"organization_usage_limit_exceeded"
组织已达到 OpenAI 分配的用量上限。
"billing_not_active"
账户尚未启用计费。
"credit_balance_exhausted"
组织的 API 余额已经用尽。
"rate_limit_exceeded"
请求超过可用的速率限制。
"flex_unavailable"
Flex 处理暂时不可用。
"server_overloaded"
模型服务暂时过载。
"cyber_policy"
请求因安全策略被拒绝。
"misalignment_policy_violation"
请求被安全系统拦截。
"connection_failed"
请求未能连接到模型服务。
"server_error"
模型服务遇到意外错误。
"authentication_error"
API 凭证无效或权限不足。
"invalid_request"
请求包含无效输入或配置。
"resource_not_found"
请求的模型或资源不可用。
"sandbox_error"
请求未能在其执行环境中完成。
"executor_version_incompatible"
执行器必须升级后才能运行此轮。
"active_turn_not_steerable"
请求运行期间,会话无法接收额外输入。
"request_timeout"
模型服务响应前,请求已超时。
"internal_error"
意外的内部错误导致会话请求未能完成。
message: string
可向客户显示的失败原因。
minLength: 0
object: "agent.session.turn" (default: "agent.session.turn")
对象类型,固定为 agent.session.turn。
"agent.session.turn"
session_id: string
此轮次所属会话的 ID。
minLength: 0
started_at: integer or null
轮次开始时的 Unix 时间戳,单位为秒。
format: int64
status: "queued" or "in_progress" or "waiting" or 3 more
轮次当前的状态。
"queued"
轮次正在等待开始。
"in_progress"
轮次正在进行。
"waiting"
轮次正在等待外部输入。
"completed"
轮次已成功完成。
"failed"
轮次失败。
"cancelled"
轮次已取消。
subagent_id: string or null
执行此轮的子智能体 ID(如适用)。
minLength: 0
usage: TokenUsage or null
本轮可统计到的词元用量。用量未知时为 null,已记录的用量可能变化。
input_tokens: integer
智能体使用的输入词元数。
format: int64
input_tokens_details: object { cached_tokens }
智能体输入词元用量的明细。
cached_tokens: integer
从提示词缓存中读取的输入词元数。
format: int64
output_tokens: integer
智能体生成的输出词元数。
format: int64
output_tokens_details: object { reasoning_tokens }
智能体输出词元用量的明细。
reasoning_tokens: integer
用于推理的输出词元数。
format: int64
total_tokens: integer
智能体使用的输入词元与输出词元的总数。
format: int64
prompt_cache_options: optional object { ttl } or null
本轮开始时选用的提示词缓存时长,可继承会话的缓存生存时间。使用模型默认值或未记录缓存时长时为 null。
ttl: "30m" or "12h"
"30m"
"12h"
first_id: string or null
data 中第一项的资源 ID。当前页为空时为 null。
minLength: 0
has_more: boolean
当前页之后是否还有可获取的资源。
last_id: string or null
data 中最后一项的资源 ID。当前页为空时为 null。翻页时,将它作为 after 传入,并保持排序和筛选条件一致。
minLength: 0
object: "list" (default: "list")
对象类型,恒为 list。
"list"
示例
## 从环境变量读取 API 密钥。
## 将 SESSION_ID 设置为目标会话的 ID。
curl https://api.openai.com/v1/agents/sessions/$SESSION_ID/turns \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY"
200 响应示例
字段名、类型值和示例标识均按接口定义保留。
{
"data": [
{
"id": "id",
"agent_id": "agent_id",
"completed_at": 0,
"created_at": 0,
"error": {
"code": "context_length_exceeded",
"message": "message"
},
"object": "agent.session.turn",
"session_id": "session_id",
"started_at": 0,
"status": "queued",
"subagent_id": "subagent_id",
"usage": {
"input_tokens": 0,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 0,
"output_tokens_details": {
"reasoning_tokens": 0
},
"total_tokens": 0
},
"prompt_cache_options": {
"ttl": "30m"
}
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
取得轮次 ID 后,可获取会话轮次以查看其状态。

TRAE-AI编程


更多建议: