# 获取会话列表

> 分页获取应用、Skill 调试或外链场景下的历史会话列表，支持按创建时间、更新时间范围及对话来源进行筛选。

Source: https://doc.fastgpt.cn/openapi/reference/chat-history/get-histories
Last Updated: 2026-11-18

## 端点概览

* **HTTP 方法**：`POST`
* **请求路径**：`/api/core/chat/history/getHistories`
* **所属模块**：对话 / 会话管理
* **鉴权方式**：`Authorization: Bearer <apiKey>`—支持 **应用 API Key**（无需 `appId`）与 **个人密钥**（需传 `appId`）；另支持 `authProxy` 团队成员代理与 `outLinkAuthData` 外链分享（详见 [API 入门：完成首次请求](https://doc.fastgpt.cn/openapi/intro)）
* **在线调试**：[在云服务 Scalar 调试台打开](https://cloud.fastgpt.cn/apidoc/systemopenapi#tag/%E4%BC%9A%E8%AF%9D%E7%AE%A1%E7%90%86/POST/core/chat/history/getHistories)（自部署实例请将域名替换为 `<instance>/apidoc/systemopenapi#tag/%E4%BC%9A%E8%AF%9D%E7%AE%A1%E7%90%86/POST/core/chat/history/getHistories`）

## 接口说明与注意事项

分页获取会话列表

## 请求参数

### Request Body 请求体（`application/json`）

#### 各分支公共字段

| 字段                | 类型       | 必填 | 默认值 | 约束与说明  |
| ----------------- | -------- | -- | --- | ------ |
| `startCreateTime` | `string` | 否  | -   | 创建时间开始 |
| `endCreateTime`   | `string` | 否  | -   | 创建时间结束 |
| `startUpdateTime` | `string` | 否  | -   | 更新时间开始 |
| `endUpdateTime`   | `string` | 否  | -   | 更新时间结束 |

**互斥参数分支（`anyOf` 选填其一）**

* **应用会话**

通过 appId 定位会话。接口同时支持 API Key 和登录态时，Authorization 优先于 token/Cookie。

| 字段           | 类型              | 必填 | 默认值 | 约束与说明                                                                                                                                                                        |
| ------------ | --------------- | -- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `appId`      | `string`        | 是  | -   | 应用 ID，使用接口允许的请求头凭证鉴权。正则：`^[0-9a-fA-F]{24}$`                                                                                                                                  |
| `sourceType` | `string` (enum) | 否  | -   | appId 对应的会话资源类型。缺省为 App 会话；辅助生成会话传对应 sourceType。可选值：`app` , `chatAgentHelper` , `workflowBuilder`                                                                            |
| `source`     | `string` (enum) | 否  | -   | 对话来源筛选；应用 API Key 固定查询 API 来源，无需传入。可选值：`test` , `online` , `share` , `api` , `cronJob` , `feishu` , `official_account` , `wecom` , `wechat` , `mcp` , `dingtalk` , `unknown` |

**默认身份**: 不传 customUid 和 authProxy，沿用凭证对应的团队成员身份。适用于直接以当前鉴权成员调用应用。

**自定义使用者**: 通过 customUid 对接自己平台的使用者，不改变鉴权成员及权限。发起对话时作为使用者和工作流 userId；管理对话时按该值限制使用者范围。

| 字段          | 类型       | 必填 | 默认值 | 约束与说明                                                                                                                                |
| ----------- | -------- | -- | --- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `customUid` | `string` | 是  | -   | 仅普通应用的 API Key 调用支持。精确匹配对话的外部使用者 ID（outLinkUid），不匹配 tmbId；省略时保留原访问范围，传入时限制读取、修改及删除。最长 1024 字符，不接受空字符串或 null，不改变鉴权成员。最小长度：1；最大长度：1024 |

**代理团队成员**: 通过 authProxy 代表同团队成员执行，解析出有效 tmbId 后按该成员权限校验。仅开启代理权限的个人密钥可用，与 customUid 互斥。

| 字段                   | 类型       | 必填 | 默认值 | 约束与说明                                                                                                  |
| -------------------- | -------- | -- | --- | ------------------------------------------------------------------------------------------------------ |
| `authProxy`          | `object` | 是  | -   | API Key 代理调用身份。仅开启 authProxy 的个人密钥可用；按团队成员 ID 或用户名指定，二者同时传入时优先使用 tmbId，解析时过滤 username；tmbId 无效时不回退到用户名 |
| `authProxy.tmbId`    | `string` | 是  | -   | **分支：按团队成员 ID**。API Key 代理调用的团队成员 ID，优先于 username。正则：`^[0-9a-fA-F]{24}$`                               |
| `authProxy.username` | `string` | 是  | -   | **分支：按用户名**。API Key 代理调用的团队成员用户名。最小长度：1；最大长度：128                                                       |

**互斥参数分支（`anyOf` 选填其一）**

* **按偏移量获取**

通过 offset 指定起始位置，从 0 开始；同时传入页码时优先使用 offset。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                 |
| ---------- | --------- | -- | ---- | ----------------------------------------------------- |
| `offset`   | `integer` | 是  | -    | **互斥参数组：分页参数**。偏移量，从 0 开始。最小值：0；最大值：9007199254740991  |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500 |

* **按页码获取**

通过页码获取，默认第 1 页；pageSize 控制每页条数。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                       |
| ---------- | --------- | -- | ---- | ----------------------------------------------------------- |
| `pageNum`  | `integer` | 否  | `1`  | **互斥参数组：分页参数**。页码，从 1 开始；传入 offset 时忽略。最大值：9007199254740991 |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500       |

* **Skill 调试会话**

通过 skillId 定位调试会话，优先于 appId 并忽略其 sourceType，使用接口允许的请求头凭证鉴权。

| 字段        | 类型              | 必填 | 默认值 | 约束与说明                                                                                                                                                                        |
| --------- | --------------- | -- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `skillId` | `string`        | 是  | -   | Skill Edit 调试 ID，使用接口允许的请求头凭证鉴权。正则：`^[0-9a-fA-F]{24}$`                                                                                                                       |
| `source`  | `string` (enum) | 否  | -   | 对话来源筛选；应用 API Key 固定查询 API 来源，无需传入。可选值：`test` , `online` , `share` , `api` , `cronJob` , `feishu` , `official_account` , `wecom` , `wechat` , `mcp` , `dingtalk` , `unknown` |

**按偏移量获取**: 通过 offset 指定起始位置，从 0 开始；同时传入页码时优先使用 offset。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                 |
| ---------- | --------- | -- | ---- | ----------------------------------------------------- |
| `offset`   | `integer` | 是  | -    | **互斥参数组：分页参数**。偏移量，从 0 开始。最小值：0；最大值：9007199254740991  |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500 |

**按页码获取**: 通过页码获取，默认第 1 页；pageSize 控制每页条数。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                       |
| ---------- | --------- | -- | ---- | ----------------------------------------------------------- |
| `pageNum`  | `integer` | 否  | `1`  | **互斥参数组：分页参数**。页码，从 1 开始；传入 offset 时忽略。最大值：9007199254740991 |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500       |

* **外链会话**

通过 outLinkAuthData 解析真实应用，优先于 skillId 和 appId 并忽略其 sourceType。外链身份优先于请求头身份；token/Cookie 可以同时传入，受保护外链仍会校验登录态。外链校验失败时不会回退到普通资源鉴权。

| 字段                           | 类型              | 必填 | 默认值 | 约束与说明                                                                                                                                                                        |
| ---------------------------- | --------------- | -- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outLinkAuthData`            | `object`        | 是  | -   | 外链鉴权数据，包含 shareId/outLinkUid。优先于 skillId 和 appId，忽略低优先级字段；允许同时携带 token/Cookie，受保护外链仍需校验登录态。                                                                                  |
| `outLinkAuthData.shareId`    | `string`        | 是  | -   | 分享链接 ID。最小长度：1                                                                                                                                                               |
| `outLinkAuthData.outLinkUid` | `string`        | 是  | -   | 外链用户 ID。最小长度：1                                                                                                                                                               |
| `source`                     | `string` (enum) | 否  | -   | 对话来源筛选；应用 API Key 固定查询 API 来源，无需传入。可选值：`test` , `online` , `share` , `api` , `cronJob` , `feishu` , `official_account` , `wecom` , `wechat` , `mcp` , `dingtalk` , `unknown` |

**按偏移量获取**: 通过 offset 指定起始位置，从 0 开始；同时传入页码时优先使用 offset。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                 |
| ---------- | --------- | -- | ---- | ----------------------------------------------------- |
| `offset`   | `integer` | 是  | -    | **互斥参数组：分页参数**。偏移量，从 0 开始。最小值：0；最大值：9007199254740991  |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500 |

**按页码获取**: 通过页码获取，默认第 1 页；pageSize 控制每页条数。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                       |
| ---------- | --------- | -- | ---- | ----------------------------------------------------------- |
| `pageNum`  | `integer` | 否  | `1`  | **互斥参数组：分页参数**。页码，从 1 开始；传入 offset 时忽略。最大值：9007199254740991 |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500       |

* **应用 API Key（无需 appId）**

Authorization 使用绑定应用的 APP API Key 时无需传 appId 或 sourceType，服务端从 Key 绑定取得应用，sourceType 固定为 app。个人密钥和登录态不能使用此省略方式；显式传入 appId 时仍以 Key 绑定为准。

**默认身份**: 不传 customUid 和 authProxy，沿用凭证对应的团队成员身份。适用于直接以当前鉴权成员调用应用。

**自定义使用者**: 通过 customUid 对接自己平台的使用者，不改变鉴权成员及权限。发起对话时作为使用者和工作流 userId；管理对话时按该值限制使用者范围。

| 字段          | 类型       | 必填 | 默认值 | 约束与说明                                                                                                                                |
| ----------- | -------- | -- | --- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `customUid` | `string` | 是  | -   | 仅普通应用的 API Key 调用支持。精确匹配对话的外部使用者 ID（outLinkUid），不匹配 tmbId；省略时保留原访问范围，传入时限制读取、修改及删除。最长 1024 字符，不接受空字符串或 null，不改变鉴权成员。最小长度：1；最大长度：1024 |

**互斥参数分支（`anyOf` 选填其一）**

* **按偏移量获取**

通过 offset 指定起始位置，从 0 开始；同时传入页码时优先使用 offset。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                 |
| ---------- | --------- | -- | ---- | ----------------------------------------------------- |
| `offset`   | `integer` | 是  | -    | **互斥参数组：分页参数**。偏移量，从 0 开始。最小值：0；最大值：9007199254740991  |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500 |

* **按页码获取**

通过页码获取，默认第 1 页；pageSize 控制每页条数。

| 字段         | 类型        | 必填 | 默认值  | 约束与说明                                                       |
| ---------- | --------- | -- | ---- | ----------------------------------------------------------- |
| `pageNum`  | `integer` | 否  | `1`  | **互斥参数组：分页参数**。页码，从 1 开始；传入 offset 时忽略。最大值：9007199254740991 |
| `pageSize` | `integer` | 否  | `20` | **互斥参数组：分页参数**。每页条数，默认 20，最大 500，超出自动按 500 处理。最大值：500       |

## 请求示例

调用前请将 `YOUR_API_KEY` 与示例 ID 替换为真实值；私有化部署实例请将基础域名替换为 `<instance>/api`。

### cURL 请求示例

```bash
curl --fail-with-body -X POST "https://cloud.fastgpt.cn/api/core/chat/history/getHistories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "appId": "68ad85a7463006c963799a05",
  "offset": 0
}'
```

### 最小合法 JSON 请求体示例

```json
{
  "appId": "68ad85a7463006c963799a05",
  "offset": 0
}
```

## 响应结构与示例

除兼容 OpenAI 协议的对话补全或二进制下载接口外，成功响应统一包裹在 `{ "code": 200, "statusText": "", "message": "", "data": ... }` 标准结构中；下方 `200` 字段表对应 `data` 载荷结构（若契约未声明具体载荷结构，请以上方状态描述及实际响应为准）。

### HTTP 200

成功获取会话列表

**Content-Type** : `application/json`

| 字段                          | 类型              | 必填 | 默认值  | 约束与说明                                                          |
| --------------------------- | --------------- | -- | ---- | -------------------------------------------------------------- |
| `total`                     | `number`        | 是  | `0`  | -                                                              |
| `list`                      | `object[]`      | 是  | `[]` | -                                                              |
| `list[].chatId`             | `string`        | 是  | -    | 最大长度：1024                                                      |
| `list[].updateTime`         | `string`        | 是  | -    | -                                                              |
| `list[].customTitle`        | `string`        | 否  | -    | -                                                              |
| `list[].title`              | `string`        | 是  | -    | -                                                              |
| `list[].top`                | `boolean`       | 否  | -    | -                                                              |
| `list[].chatGenerateStatus` | `number` (enum) | 否  | -    | 由 Redis 生成租约计算的运行状态：0=generating（生成中），1=done（空闲）。可选值：`0` , `1` |
| `list[].hasBeenRead`        | `boolean`       | 否  | -    | -                                                              |
