# 分页查询会话消息列表

`GET` `/api/session/messages`

根据会话ID或业务键(bizKey)分页查询消息列表。bizKey与sessionId二选一，bizKey优先级更高。默认按对话时间升序返回（sortOrder=asc），旧消息在前；传入sortOrder=desc时按时间倒序返回，新消息在前，第1页即最新消息，适合查询最近聊天记录的场景。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

## 请求参数

### 请求头参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| X-Principal-Id | integer | 否 | 身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。 |

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | integer | 否 | 会话ID，与bizKey二选一 |
| bizKey | string | 否 | 业务键，与sessionId二选一，优先级高于sessionId |
| page | integer | 否 | 页码，从1开始 |
| pageSize | integer | 否 | 每页记录数 |
| sortOrder | string | 否 | 排序方式，可选值：asc（升序，旧消息在前，默认）、desc（倒序，新消息在前，第1页即最新消息），大小写不敏感 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | PageResultMessageItemVO | 响应数据 |
|     items | array | 数据列表 |
|         messageId | integer | 消息ID |
|         sessionId | integer | 会话ID |
|         role | string | 角色：USER / ASSISTANT |
|         userInput | string | 用户输入内容 |
|         attachments | array | 消息附件列表 |
|             attachmentId | integer | 附件ID |
|             fileName | string | 文件名。智能体生成的附件此字段可能带相对工作区的路径前缀，如 agent_session/tmp/报告.pdf；展示文件名请改用 pureFileName |
|             pureFileName | string | 纯文件名（已剥离目录部分），展示附件名称时请用此字段 |
|             fileExtension | string | 文件扩展名 |
|             contentType | string | 文件MIME类型 |
|             fileSize | integer | 文件大小（字节） |
|             virtualPath | string | 虚拟路径 |
|             source | string | 附件来源：USER_UPLOAD / AGENT_GENERATED |
|             previewUrl | string | 附件预览URL，前端可直接用于图片渲染或文件预览 |
|         messageStatus | string | 消息状态 |
|         errorMessage | string | 错误信息 |
|         replyMessageId | integer | 回复消息ID |
|         startTime | string | 开始时间 |
|         endTime | string | 结束时间 |
|         totalPromptTokens | integer | 总Prompt Token数 |
|         totalCompletionTokens | integer | 总Completion Token数 |
|         totalTokens | integer | 总Token数 |
|         totalCachedTokens | integer | 总缓存Token数 |
|         totalReasoningTokens | integer | 总推理Token数 |
|         gmtCreate | string | 创建时间 |
|     total | integer | 总记录数 |
|     page | integer | 当前页码，从1开始 |
|     pageSize | integer | 每页大小 |
|     totalPages | integer | - |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 400

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |

### 500

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | object | 响应数据 |
| success | boolean | 是否成功 |
| requestId | string | 上游请求ID，用于跨系统链路追踪排查问题 |
| errCode | string | 上游错误码，前端可据此做特殊UI处理 |