# List UI protocol session messages

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

Read the current user's messages using an ID cursor; returns a message array.


```http
POST https://api.moi.matrixorigin.cn/v5/messages/session/list
```

## Before you call this API

Set `BASE_URL` to the product API prefix `https://api.moi.matrixorigin.cn/v5`. For private deployments, use the corresponding product API URL.

[Configure identity, Workspace, and numeric record IDs in the same environment](objects.md#prepare). This entry point uses ordinary product authentication and rejects additional task runtime authorization headers.

## Request

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

```bash
curl --request POST \
  "$BASE_URL/messages/session/list" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-raw '{"session_id":41,"after":0,"limit":50}'
```

If the previous page ends with message ID 71, use this complete request for the next page:

```bash
curl --request POST \
  "$BASE_URL/messages/session/list" \
  --header "X-API-Key: $MOI_KEY" \
  --header "X-Workspace-ID: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data-raw '{"session_id":41,"after":71,"limit":50}'
```

:::::
:::::{tab-item} Parameters

| Parameter | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Workspace-ID` | Headers | string | Yes | Target Workspace ID. |
| `session_id` | Body | integer | Yes | Positive integer session ID in this service; use a number in JSON. |
| `after` | Body | integer | No | Returns messages whose IDs exceed this value; nonpositive values become 0. |
| `limit` | Body | integer | No | Defaults to 50. Nonpositive values or values above 100 become 50. |
| `role` | Body | string | No | user/system/assistant participate in filtering; other strings mean no filtering. |
| `status` | Body | string | No | Record status filter; surrounding whitespace is removed. |
| `source` | Body | string | No | Accepted by binding but not used in current filtering. |
| `model` | Body | string | No | Accepted by binding but not used in current filtering. |

data is directly a message array without a messages, total, or next_cursor wrapper. Messages sort by ascending ID. For the next page, use the last message ID as after; stop on an empty array. Empty results do not independently establish session existence. Roles are strings, unlike the Workspace protocol's integers. The internal agent_tool role maps to user in this response.

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

## Successful response

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": [
    {
      "id": 71,
      "user_id": "user-example",
      "session_id": 41,
      "source": "moi",
      "role": "assistant",
      "original_content": "",
      "content": "已有消息",
      "model": "",
      "status": "completed",
      "config": "",
      "response": "已有回答",
      "modified_response": "",
      "tags": [],
      "created_at": 1794445200,
      "updated_at": 1794445200
    }
  ]
}
```

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

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success; HTTP status is 200. |
| `msg` | string | OK on success. |
| `data` | array (objects) | Current page of [Message objects](objects.md#message-object); an empty array when nothing matches. |

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

## Error responses

[Error formats and result confirmation](objects.md#error-contract) distinguishes session-detail not-found from generic service errors at other entry points.
