列出 Sessions

GET /api/v1/forward/sessions 返回当前账号下的 Session 列表，默认按创建时间倒序排列；归档 Session 默认不返回。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT 或 SAT>`

查询参数

参数	类型	是否必填	默认值	说明
search	string	否	-	搜索关键字。值以 `sess_` 开头时优先按 Session ID 精确匹配，否则按标题匹配。匹配规则见备注。
identity_ids	string或array	否	-	按一个或多个 Identity ID 过滤，支持逗号分隔。
template_id	string	否	-	按 Forward Template ID 过滤。
source_type	string	否	-	按 `api`、`im`、`schedule` 或 `batch` 过滤。
created_at[gt]	string	否	-	创建时间严格大于该 RFC 3339 时间。
created_at[gte]	string	否	-	创建时间大于等于该 RFC 3339 时间。
created_at[lt]	string	否	-	创建时间严格小于该 RFC 3339 时间。
created_at[lte]	string	否	-	创建时间小于等于该 RFC 3339 时间。
updated_at[gt]	string	否	-	更新时间严格大于该 RFC 3339 时间。
updated_at[gte]	string	否	-	更新时间大于等于该 RFC 3339 时间。
updated_at[lt]	string	否	-	更新时间严格小于该 RFC 3339 时间。
updated_at[lte]	string	否	-	更新时间小于等于该 RFC 3339 时间。
limit	integer	否	20	分页大小，最大 100。
after_id	string	否	-	向后翻页游标，传入上一页响应的 `last_id`。
before_id	string	否	-	向前翻页游标，传入当前页响应的 `first_id`。
order	string	否	desc	创建时间排序方向：`desc` 或 `asc`。
include_archived	boolean	否	false	是否包含已归档 Session。

示例请求

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

按标题关键字搜索：

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions?search=support' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

按 Session ID 精确查找：

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions?search=sess_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

查询下一页：

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions?limit=20&order=desc&after_id=sess_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

示例响应

HTTP 200 OK

{
  "data": [
    {
      "id": "sess_xxx",
      "type": "session",
      "identity_id": "idn_xxx",
      "template": {
        "id": "tmpl_support",
        "type": "template",
        "name": "Support assistant",
        "model": "ultimate",
        "version": 3
      },
      "source_type": "im",
      "status": "idle",
      "title": "Customer support session",
      "metadata": {
        "source": "dingtalk"
      },
      "config": {
        "environment_variables": {
          "API_KEY": "sk-xxx"
        }
      },
      "resources": [
        {
          "id": "sesr_xxx",
          "type": "file",
          "file_id": "file_xxx",
          "mount_path": "/data/workspace/spec.md",
          "created_at": "2026-06-23T05:53:19Z",
          "updated_at": "2026-06-23T05:53:38Z"
        }
      ],
      "stats": {
        "active_seconds": 30,
        "duration_seconds": 3600
      },
      "usage": {
        "total_credits": 12.5
      },
      "archived_at": null,
      "created_at": "2026-06-22T10:00:00Z",
      "updated_at": "2026-06-22T11:00:00Z"
    }
  ],
  "first_id": "sess_xxx",
  "last_id": "sess_xxx",
  "has_more": false
}

响应字段

字段	类型	说明
data	array	当前页的 Session 对象。
first_id	string\|null	当前页第一条记录 ID。
last_id	string\|null	当前页最后一条记录 ID。
has_more	boolean	是否还有更多记录。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	`invalid_time_range`	时间筛选范围不合法。
400	`invalid_request_error`	`invalid_time_filter`	时间筛选格式不合法。
400	`invalid_request_error`	`invalid_pagination`	分页参数不合法。
400	`invalid_request_error`	`invalid_limit`	`limit` 不合法或超过最大值。
400	`invalid_request_error`	`invalid_order`	`order` 不是 `asc` 或 `desc`。
400	`invalid_request_error`	`invalid_search`	`search` 不是合法 UTF-8、超过 512 字节或包含控制字符。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

search 匹配规则：

以 sess_ 开头时，优先按 Session ID 精确匹配；命中时仅返回该 Session，未命中时回退为标题匹配。
标题匹配为大小写不敏感的子串匹配；%、_、\ 按字面字符匹配。
自动去除首尾空白；值必须为合法 UTF-8，最长 512 字节，且不能包含控制字符。

其他说明：

after_id 和 before_id 不能同时传入。
列表按 created_at 排序；创建时间相同时按 Session ID 同方向排序，保证分页稳定。
连续翻页时应保持相同的筛选条件和 order。
当前设计不支持按 status 筛选。
usage.total_credits 仅新创建的 Session 返回；历史 Session 可能会省略。
resources 返回 Session 挂载的资源列表，当前仅包含通过添加 Session 资源接口添加的 file 类型资源；无资源时为空数组。

请求头

查询参数

示例请求

示例响应

响应字段

错误

备注

相关

创建 Session

获取 Session

​请求头

​查询参数

​示例请求

​示例响应

​响应字段

​错误

​备注

​相关

创建 Session

获取 Session

请求头

查询参数

示例请求

示例响应

响应字段

错误

备注

相关