# 查询会话条目列表

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

查询本地会话中的条目摘要。

```text
GET https://token.moi.matrixorigin.cn/v1/conversations/{conversation_id}/items
```

## 调用前准备

1. 准备具有 Genesis 权限的[个人访问令牌](../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)。
2. 使用[创建会话](create-conversation.md)时的凭据，选择尚未删除、尚未关联上游模型的本地会话。

## 请求示例

将示例中的 `$GENESIS_ACCESS_TOKEN` 和 `$CONVERSATION_ID` 分别替换为个人访问令牌和所选会话的 ID。

```bash
curl -X GET "https://token.moi.matrixorigin.cn/v1/conversations/$CONVERSATION_ID/items?limit=100&order=asc" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN"
```

## 路径参数

::::{div} mo-api-parameter-table

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `conversation_id` | string | 是 | 创建会话响应中的 `id`。 |

::::

## 查询参数

::::{div} mo-api-parameter-table

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `limit` | integer | 否 | 返回条目数。默认 100；超过 200 时按 200 处理；非正整数或无法解析时使用默认值。 |
| `order` | string | 否 | 默认按创建时间升序取数；传入 `desc` 时，将已截取的返回集合倒序展示。 |

::::

本地会话条目最多返回 200 条，暂不支持通过 `after` 游标翻页。需要完整历史记录时，由应用保存条目与消息正文。

## 成功响应

成功时返回会话的条目摘要列表。

本地条目保存类型、角色和状态等摘要；消息正文需由应用自行保存。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "object": "list",
  "data": [
    {
      "id": "$ITEM_ID",
      "object": "conversation.item",
      "conversation_id": "$CONVERSATION_ID",
      "type": "message",
      "role": "user",
      "status": "active",
      "created_at": 1780000000
    }
  ],
  "first_id": "$ITEM_ID",
  "last_id": "$ITEM_ID",
  "has_more": false
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `object` | string | 固定为 `list`。 |
| `data` | array of object | 当前返回的条目摘要。 |
| `data[].id` | string | 条目标识。 |
| `data[].object` | string | 固定为 `conversation.item`。 |
| `data[].conversation_id` | string | 条目所属的会话标识。 |
| `data[].type` | string | 条目类型，例如 `message`。 |
| `data[].role` | string | 条目角色，例如 `user`。 |
| `data[].status` | string | 条目状态，省略时为 `active`。 |
| `data[].created_at` | integer | 创建时间，Unix 秒级时间戳。 |
| `first_id` | string | 第一条结果的标识；空列表时为空字符串。 |
| `last_id` | string | 最后一条结果的标识；空列表时为空字符串。 |
| `has_more` | boolean | 本地响应固定为 `false`；该值无法用于判断条目是否被 `limit` 截断。 |

:::::
::::::
:::::::

## 错误响应

资源不存在、已删除或当前凭据不可访问时，请求返回 `404`。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "error": {
    "message": "conversation not found",
    "type": "conversation_not_found",
    "code": "conversation_not_found"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error` | object | 错误信息。 |
| `error.message` | string | 错误原因。 |
| `error.type` | string | 错误类别。 |
| `error.code` | string | 错误代码。 |

:::::
::::::
:::::::

## 后续操作

使用 `data` 中目标条目的 `id` [查询会话条目](get-item.md)。