> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 列出 Sessions

> 按筛选条件分页列出 Forward Session。

`GET /api/v1/forward/sessions`

返回当前账号下的 Session 列表；归档 Session 默认不返回。

## 请求头

| Header        | 是否必填 | 说明             |
| ------------- | ---- | -------------- |
| Authorization | 是    | `Bearer <PAT>` |

## 查询参数

| 参数                | 类型           | 是否必填 | 默认值   | 说明                            |
| ----------------- | ------------ | ---- | ----- | ----------------------------- |
| identity\_ids     | string或array | 否    | -     | 按一个或多个 Identity ID 过滤，支持逗号分隔。 |
| template\_id      | string       | 否    | -     | 按 Forward Template ID 过滤。     |
| source\_type      | string       | 否    | -     | 按 `api`、`im` 或 `schedule` 过滤。 |
| 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       | 否    | -     | 向后翻页游标。                       |
| before\_id        | string       | 否    | -     | 向前翻页游标。                       |
| order             | string       | 否    | desc  | 排序方向：`desc` 或 `asc`。          |
| include\_archived | boolean      | 否    | false | 是否包含已归档 Session。              |

## 示例请求

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_PAT"
```

## 示例响应

**HTTP 200 OK**

```json theme={null}
{
  "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",
      "incremental_streaming_enabled": true,
      "metadata": {
        "source": "dingtalk"
      },
      "config": {
        "environment_variables": {
          "API_KEY": "sk-xxx"
        }
      },
      "stats": {
        "active_seconds": 30,
        "duration_seconds": 3600
      },
      "usage": {
        "credits": 12.5
      },
      "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_pagination`      | 分页参数不合法。    |
| 401  | `authentication_error`  | `authentication_required` | PAT 无效或已过期。 |

## 注意事项

* `after_id` 和 `before_id` 不能同时传入。
* 当前设计不支持按 `status` 筛选。
* Credits 模块未启用时可省略 `usage.credits`。

## 相关

<CardGroup cols={2}>
  <Card title="创建 Session" icon="plus" href="/cloud-agents/api/forward/sessions/create" />

  <Card title="获取 Session" icon="file-lines" href="/cloud-agents/api/forward/sessions/get" />
</CardGroup>