# 查询消息完整调用元数据

`GET` `/api/sessionAnalysis/messageTrace`

一次返回助手消息或压缩承载消息的全部已归档请求引用和步骤元数据；用户消息ID自动解析助手回复。无归档步骤返回STEP_ONLY，不推断缺失原因。列表不读取原始请求正文。相同步骤的统计可能重复，须按stepId去重；轮内压缩的锚定步骤统计不代表该压缩调用的独立结果。单消息最多2000份归档，超过上限明确报错。

## 请求参数

### 请求头参数

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

### Query 参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | integer | 是 | 会话ID |
| messageId | integer | 是 | 助手或压缩承载消息ID；消息查询支持用户消息解析回复，下载不自动解析 |
| stepIndex | integer | 否 | 步骤号，STEP从1起，轮间压缩为0；不传查询全部 |
| kind | string | 否 | 调用类型，可选值：STEP、COMPACT；不传查询全部 |

## 响应

### 200

| 参数名 | 类型 | 说明 |
|--------|------|------|
| httpStatusCode | integer | HTTP状态码 |
| message | string | 响应消息 |
| data | MessageAnalysisVO | 响应数据 |
|     sessionId | integer | 会话ID |
|     messageId | integer | 实际分析的助手或压缩承载消息ID |
|     userMessageId | integer | 关联用户消息ID |
|     status | string | 消息状态，可选值：PROCESSING、COMPLETED、FAILED、WAITING_PERMISSION、UNKNOWN |
|     modelName | string | 消息级已有模型名称 |
|     startTime | string | 消息已有开始时间 |
|     endTime | string | 消息已有结束时间 |
|     tokenUsage | TokenUsageVO | 整条消息Token统计，不受筛选条件影响 |
|         promptTokens | integer | 输入Token，未知时为空 |
|         completionTokens | integer | 输出Token，未知时为空 |
|         totalTokens | integer | 总Token，直接使用存储值 |
|         cachedTokens | integer | 缓存Token |
|         reasoningTokens | integer | 推理Token |
|     items | array | 该消息命中筛选条件的全部调用与步骤记录，最多2000份归档 |
|         recordType | string | REQUEST为已归档请求；STEP_ONLY为仅有步骤，可选值：REQUEST、STEP_ONLY |
|         kind | string | 调用类型，可选值：STEP、COMPACT |
|         stepIndex | integer | 所属或锚定步骤 |
|         llmRequestId | string | REQUEST必有；STEP_ONLY为空 |
|         attempt | integer | STEP请求体版本 |
|         compactSeq | integer | 压缩批内序号 |
|         rerunId | string | 重跑另存标识 |
|         step | StepMetadataVO | 关联步骤；重复出现时请按stepId去重，统计不是单份归档结果 |
|             stepId | integer | 数据库步骤ID |
|             stepType | string | 步骤类型，可选值：LLM_CALL、COMPACT |
|             status | string | 步骤状态，可选值：COMPLETED、FAILED、UNKNOWN |
|             modelResponseId | string | 步骤保存的模型响应ID |
|             llmStartTime | string | 步骤保存的模型开始时间 |
|             llmDurationMs | integer | 步骤模型耗时，毫秒 |
|             llmTtftMs | integer | 首Token耗时，毫秒 |
|             stepOverheadMs | integer | 步骤额外开销，毫秒 |
|             tokenUsage | TokenUsageVO | 步骤级统计；不能按重复调用记录直接累加 |
|                 promptTokens | integer | 输入Token，未知时为空 |
|                 completionTokens | integer | 输出Token，未知时为空 |
|                 totalTokens | integer | 总Token，直接使用存储值 |
|                 cachedTokens | integer | 缓存Token |
|                 reasoningTokens | integer | 推理Token |
| 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处理 |