文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯云数据库 AI 服务>Memory 应用指南>开发者参考>Python>原始会话>query_conversation — 查询原始对话消息

query_conversation — 查询原始对话消息

最近更新时间：2026-05-26 21:12:00

我的收藏

本页目录：

接口介绍

按条件分页查询原始对话消息。传入分页参数与筛选参数，即可一次返回命中条件的消息列表与命中总数：
分页控制：通过 limit 指定单页条数、offset 指定起始偏移；不传时按服务端默认值 limit=20、offset=0 返回第一页。
筛选条件：通过 session_id 限定会话，time_start / time_end 限定时间窗（含端点）。三者均可选，全部缺省时等价于不加筛选，仅按分页返回。
项
值
HTTP 方法与路径
POST /v2/conversation/query
HTTP 文档
函数签名
query_conversation(*, session_id=None, limit=None, offset=None, time_start=None, time_end=None)
说明：
当您将可选参数设置为 None（空）时，SDK 在发送请求前会自动过滤掉这些参数，不会将它们发送给服务器。

使用示例

# 查询某会话的最近 20 条消息
result = client.query_conversation(session_id="sess-trip-202604")
for msg in result["data"]["messages"]:
    print(f"[{msg['role']}] {msg['content']}")

# 翻页：第 21~40 条
result = client.query_conversation(
    session_id="sess-trip-202604",
    limit=20,
    offset=20,
)

# 按时间窗筛选
result = client.query_conversation(
    time_start="2026-05-01T00:00:00+08:00",
    time_end="2026-05-31T23:59:59+08:00",
)
说明：
client 实例的构造方式参见 新建客户端；异步调用时将方法前加 await 即可。

请求参数

参数名
类型
必填
默认值
描述说明
session_id
str
否
-
会话 ID。传入后仅返回该特定会话下的历史消息；若不传或传 None，则默认查询所有会话。
limit
int
否
20
单页返回的条数。
限制：最大支持 100 条。
注意：若传 None，服务端将自动采用默认值 20。
offset
int
否
0
分页起始偏移量。表示跳过前多少条数据（常用于传统分页）。
time_start
str
否
-
时间筛选起点（包含该时刻）。
格式要求：需符合 ISO 8601 标准。
例如："2026-05-25T10:00:00Z" 或 "2026-05-25T18:00:00+08:00"。
time_end
str
否
-
时间筛选终点（包含该时刻）。与 time_start 配合组成闭区间时间窗。格式要求：需符合 ISO 8601 标准。

返回信息

返回字典包含命中的消息列表、命中总数与请求追踪 ID：
{
  "data": {
  "messages": [
    {
      "id": "msg-aaaa",
      "role": "user",
      "content": "我打算 5 月去日本...",
      "timestamp": "2026-05-22T14:30:00+08:00"
    }
  ],
  "total": 1
  },
  "trace_id": "tr-xxxxxxxx-xxxxxxxx"
}
字段名
类型
说明
data.messages
List[Dict]
历史消息列表。
排序规则：列表内的消息默认按时间先后顺序排列。
数据结构：每条消息包含以下完整字段：
id (str): 消息的唯一主键 ID。
role (str): 发送者角色，可选值为 "user"、"assistant" 或 "system"。
content (str): 消息的具体文本内容。
timestamp (str): 消息产生的时间戳（ISO 8601 格式）。
data.total
int
满足筛选条件的消息总条数。
注意：该值为全量数据总数，完全不受当前请求中 limit（单页条数）和 offset（偏移量）的分页限制。
应用场景：前端可直接利用该数值来计算并渲染传统的分页组件（如：总页数 = total / limit）。
trace_id
str
请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，方便前后端协同定位请求问题。

错误处理

错误码
触发场景
处理建议
400
limit / offset 越界、时间格式非法。
请校验入参后重试。
500
服务端错误。
记录 trace_id 后重试或上报。

中国站