跳转到主要内容
GET /v1/sessions/{session_id}/events 获取 Session 中的事件列表，按时间正序排列。支持游标分页。

​
请求头

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

​
路径参数

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

​
查询参数

参数类型必选说明
limitinteger否返回数量上限，默认 20
after_idstring否游标分页：返回该事件 ID 之后的记录
before_idstring否游标分页：返回该事件 ID 之前的记录
orderstring否排序方向：asc（默认，时间正序）或 desc（时间倒序）
typestring否按事件类型过滤。值与返回事件的 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_useAgent 发起工具调用tool_name, name, tool_input, tool_use_id, requires_confirmation
agent.tool_result工具执行结果tool_use_id, content (ContentBlock[]), is_error
agent.messageAgent 回复content (ContentBlock[])
agent.thinkingAgent 思考-
session.status_running会话开始执行-
session.status_idle会话回到空闲usage, status, stop_reason
session.error会话执行错误error, details, retry_status
span.model_request_start模型请求开始-
span.model_request_end模型请求结束-
agent.artifact_deliveredAgent 通过 DeliverArtifacts 工具投递了文件file_id, original_filename, size, content_type
terminated执行终止-
agent.message 的 content 格式： 
{
  "content": [
    {
      "type": "text",
      "text": "Agent 的回复文本内容"
    }
  ]
}
session.status_idle 的额外字段： 
{
  "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"
  }
}
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"
  }
}

​
响应字段

字段类型说明
dataarray事件对象列表
first_idstring当前页第一条记录的 ID
last_idstring当前页最后一条记录的 ID
has_moreboolean是否还有更多记录

​
错误码

HTTPtype触发条件
401authentication_errorPAT 无效或过期
404not_found_errorSession 不存在
完整错误信封说明详见 错误参考。

​
获取 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"