List conversation items¶

List item summaries in a local conversation.

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

Before you begin¶

Prepare a personal access token with Genesis access.
Use the credential used to Create a conversation, 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.

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¶

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

Query parameters¶

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.

Response example

{
  "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
}

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.

Response example

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

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.

Last updated on Sep 15, 2026