列出事件 - Qoder

GET /v1/sessions/{session_id}/events 获取 Session 中的事件列表，按时间正序排列。支持游标分页。如果请求 Accept 头包含 text/event-stream，同一路由会切换到 SSE 流式返回，不返回分页 JSON。需要列表响应时，请使用 Accept: application/json 或不要带 SSE media type。

请求头

头部	必选	说明
`Authorization`	是	`Bearer <PAT>`

路径参数

参数	类型	必选	说明
`session_id`	string	是	Session ID（`sess_` 前缀）

查询参数

参数	类型	必选	说明
`limit`	integer	否	返回数量上限，默认 20
`after_id`	string	否	游标分页：返回该事件 ID 之后的记录
`before_id`	string	否	游标分页：返回该事件 ID 之前的记录
`order`	string	否	排序方向：`asc`（默认，时间正序）或 `desc`（时间倒序）
`type`	string	否	按事件类型过滤。值与返回事件的 `type` 字段匹配（如 `user.message`、`agent.message`、`agent.artifact_delivered`）。支持逗号分隔传入多值（如 `type=user.message,agent.message`），也支持重复 key（如 `type=a&type=b`）。省略则返回所有类型
`types[]`	string	否	`type` 的数组写法替代方案。传入多个 `types[]=…` 参数可过滤多种事件类型（如 `types[]=user.message&types[]=agent.message`）
`created_at[gte]`	string	否	返回创建时间 ≥ 该时刻的事件（含等于）。RFC 3339 格式
`created_at[lte]`	string	否	返回创建时间 ≤ 该时刻的事件（含等于）。RFC 3339 格式

完整分页规范详见分页。

示例请求

curl -X GET "https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events?limit=5" \
  -H "Authorization: Bearer $QODER_PAT"

按事件类型过滤

# 单类型 — 只拉 Agent 文件投递事件
curl -X GET "https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events?type=agent.artifact_delivered&limit=100" \
  -H "Authorization: Bearer $QODER_PAT"

# 多类型（逗号分隔）
curl -X GET "https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events?type=user.message,agent.message&limit=100" \
  -H "Authorization: Bearer $QODER_PAT"

# 多类型（数组语法）
curl -X GET "https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events?types[]=user.message&types[]=agent.message&limit=100" \
  -H "Authorization: Bearer $QODER_PAT"

示例响应

HTTP 200 OK

{
  "data": [
    {
      "id": "evt_019e392c0d787cfaa21bda98e06cd913",
      "type": "user.message",
      "content": "你好，这是一个测试消息",
      "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def",
      "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec",
      "schema_version": "1.0",
      "created_at": "2026-05-18T03:40:48.888851795Z",
      "processed_at": "2026-05-18T03:40:48.888851795Z"
    },
    {
      "id": "evt_771c1195bcbd4a07834d4ed4dd6450ca",
      "type": "session.status_running",
      "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def",
      "turn_id": "turn_019e392c0d787ceea6bb62943f9ac3ec",
      "schema_version": "1.0",
      "created_at": "2026-05-18T03:40:50.321Z",
      "processed_at": "2026-05-18T03:40:50.321Z"
    }
  ],
  "first_id": "evt_019e392c0d787cfaa21bda98e06cd913",
  "last_id": "evt_771c1195bcbd4a07834d4ed4dd6450ca",
  "has_more": true
}

事件类型参考

type	说明	特有字段
`user.message`	用户消息	`content` (string)
`agent.tool_use`	Agent 发起内置工具调用	`name`, `input`, `evaluated_permission`
`agent.tool_result`	工具执行结果	`tool_use_id`, `content` (ContentBlock[]), `is_error`
`agent.custom_tool_use`	Agent 请求 client-side 自定义工具	`name`, `input`
`agent.mcp_tool_use`	Agent 调用 MCP 工具	`name`, `input`, `mcp_server_name`, `evaluated_permission`
`agent.mcp_tool_result`	MCP 工具执行结果	`tool_use_id`, `content` (ContentBlock[]), `is_error`
`agent.message`	Agent 回复	`content` (ContentBlock[])
`agent.thinking`	Agent 思考	-
`user.interrupt`	用户中断 Agent 执行	-
`user.tool_confirmation`	用户批准或拒绝待确认工具调用	`tool_use_id`, `result`, 可选 `deny_message`
`user.custom_tool_result`	用户/客户端返回自定义工具结果	`custom_tool_use_id`, `content` (ContentBlock[])
`user.define_outcome`	用户定义预期结果事件	事件特定 payload
`session.status_running`	会话开始执行	-
`session.status_idle`	会话回到空闲	`usage`, `status`, `stop_reason`
`session.error`	会话执行错误	`error`, `details`, `retry_status`
`agent.artifact_delivered`	Agent 通过 `DeliverArtifacts` 工具投递了文件	`file_id`, `original_filename`, `size`, `content_type`
`session.thread_created`	新子线程被创建（Managed Agents）	`parent_thread_id`, `agent_id`, `agent_version`, `agent_name`, `role`, `created_by_tool_use_id`
`session.thread_status_running`	子线程开始执行（Managed Agents）	`agent_name`, `status`
`session.thread_status_idle`	子线程回到空闲（Managed Agents）	`status`, `stop_reason`
`session.thread_status_terminated`	子线程被归档或终止（Managed Agents）	`status`, `stop_reason`
`agent.thread_message_sent`	线程间发送消息（Managed Agents）	`direction`, `content`, `from_session_thread_id`, `to_session_thread_id`
`agent.thread_message_received`	线程间接收消息（Managed Agents）	`direction`, `content`, `is_error`, `from_session_thread_id`, `to_session_thread_id`

历史接口会过滤内部事件类型，例如 agent.raw、agent.system、turn_completed、turn_cancelled、turn_failed、terminated、span.model_request_start、span.model_request_end 和 pending_action.*。 agent.message 的 content 格式：

{
  "content": [
    {
      "type": "text",
      "text": "Agent 的回复文本内容"
    }
  ]
}

session.status_idle 的额外字段： Turn 完成：

{
  "type": "session.status_idle",
  "status": "idle",
  "usage": {
    "input_tokens": 150,
    "output_tokens": 42,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  },
  "stop_reason": {
    "type": "end_turn"
  }
}

Turn 暂停等待 Human-in-the-loop 响应：

{
  "type": "session.status_idle",
  "status": "idle",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["evt_01JZ6Q3FB6SG8F7J1M2N"]
  }
}

当 stop_reason.type 为 requires_action 时，event_ids 中的值是需要客户端响应的 agent.tool_use 或 agent.custom_tool_use 事件 ID。回传时分别填入 user.tool_confirmation.tool_use_id 或 user.custom_tool_result.custom_tool_use_id。 session.error 格式：

{
  "type": "session.error",
  "error": {
    "message": "The operation was aborted due to timeout",
    "type": "unknown_error"
  },
  "details": {
    "message": "The operation was aborted due to timeout",
    "name": "TimeoutError"
  },
  "retry_status": {
    "type": "exhausted"
  }
}

响应字段

字段	类型	说明
`data`	array	可见 Event 对象列表。每个对象都包含 `id`、`type`、`session_id`、`schema_version`、`created_at`，通常也包含 `processed_at`；属于某个 turn 的事件包含 `turn_id`。其它字段取决于 `type`。
`first_id`	string	当前页第一条记录的 ID
`last_id`	string	当前页最后一条记录的 ID
`has_more`	boolean	是否还有更多记录

错误码

HTTP	type	触发条件
401	`authentication_error`	PAT 无效或过期
404	`not_found_error`	Session 不存在

完整错误信封说明详见错误参考。

获取 Agent 产出文件

当 Agent 调用 DeliverArtifacts 工具时，平台会将每个投递的文件上传到持久存储，并生成一条 agent.artifact_delivered 事件。使用 type 过滤拉取这些事件，再通过 Files API 下载文件。

`agent.artifact_delivered` 事件格式

{
  "id": "evt_019eab58a1b27c3f9012d4e5f6a7b8c9",
  "type": "agent.artifact_delivered",
  "file_id": "file_019eab58a1b27c3f9012d4e5f6a7b8c9",
  "original_filename": "hello.txt",
  "size": 28,
  "content_type": "text/plain",
  "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def",
  "turn_id": "turn_019eab56b4d77163bd7da587c553548c",
  "schema_version": "1.0",
  "created_at": "2026-06-09T07:44:26.987Z"
}

端到端下载示例

SESSION_ID=sess_abc123

# 1. 只拉文件投递事件
curl -s "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events?type=agent.artifact_delivered&limit=100" \
  -H "Authorization: Bearer $QODER_PAT" | jq '.data[] | {file_id, original_filename, size}'

# 2. 获取预签名下载 URL（需要 Authorization）
URL=$(curl -s "https://api.qoder.com/api/v1/cloud/files/$FILE_ID/content" \
  -H "Authorization: Bearer $QODER_PAT" | jq -r '.url')

# 3. 直接下载（不要带 Authorization — URL 已预签名）
curl -sL -o "$FILENAME" "$URL"

Session 事件流

通过 SSE 实时获取 Agent 的思考、消息、工具调用与状态。

​请求头

​路径参数

​查询参数

​示例请求

​按事件类型过滤

​示例响应

​事件类型参考

​响应字段

​错误码

​获取 Agent 产出文件

​agent.artifact_delivered 事件格式

​端到端下载示例

​相关