# List conversation items

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

List item summaries in a local conversation.

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

## Before you begin

1. Prepare a [personal access token](../../../../guides/billing/credentials.md#personal-access-token) with Genesis access.
2. Use the credential used to [Create a conversation](create-conversation.md), and choose a local conversation that has not been deleted or bound to an upstream model.

## Request example

Replace `$GENESIS_ACCESS_TOKEN` and `$CONVERSATION_ID` with your personal access token and the selected conversation 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"
```

## Path parameters

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | string | Yes | The `id` returned when creating the conversation. |

::::

## Query parameters

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

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Number of items to return. Defaults to 100, caps at 200, and falls back to the default for nonpositive or unparseable values. |
| `order` | string | No | Items are selected in ascending creation-time order. Use `desc` to reverse the selected result set. |

::::

Local conversation queries return at most 200 items and do not support pagination with an `after` cursor. Keep complete item history and message bodies in your application.

## Successful response

A successful request returns a list of item summaries for the conversation.

Local items retain summaries such as type, role, and status. Store message bodies in your application.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `list`. |
| `data` | array of object | Item summaries in this result set. |
| `data[].id` | string | Item identifier. |
| `data[].object` | string | Always `conversation.item`. |
| `data[].conversation_id` | string | Identifier of the conversation containing this item. |
| `data[].type` | string | Item type, such as `message`. |
| `data[].role` | string | Item role, such as `user`. |
| `data[].status` | string | Item status; defaults to `active` when omitted. |
| `data[].created_at` | integer | Creation time as a Unix timestamp in seconds. |
| `first_id` | string | Identifier of the first result, or an empty string for an empty list. |
| `last_id` | string | Identifier of the last result, or an empty string for an empty list. |
| `has_more` | boolean | Always `false` for local responses. This value does not indicate whether `limit` truncated the result. |

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

## Error response

The request returns `404` when the resource is missing, deleted, or inaccessible to the current credential.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `error` | object | Error details. |
| `error.message` | string | Error description. |
| `error.type` | string | Error type. |
| `error.code` | string | Error code. |

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

## Next steps

Use the target item’s `id` from `data` to [Retrieve a conversation item](get-item.md).