Query session messages¶

Read saved messages in visible sessions. This interface is read-only; new messages are written by the A2A runtime called by the agent and are not created through this interface.

GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/conversations/{conversation_id}/messages

Preparation before calling¶

First query session details or create session] to obtain the session ID. Prepare the personal access token, target workspace ID, and session ID that have access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$CONVERSATION_ID: The session ID of the message to be queried.
$AGENT_ID: Optional agent filter ID.

Request example¶

curl --get "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/conversations/$CONVERSATION_ID/messages" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "agent_id=$AGENT_ID" \
  --data-urlencode "role=assistant" \
  --data-urlencode "limit=50"

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Current workspace ID, must be consistent with `X-Workspace-ID`.
`conversation_id`	string	Yes	The session ID of the message to be queried.

Query parameters¶

Parameters	Type	Is it required	Description
`agent_id`	string	No	Only queries sessions belonging to the specified agent. Does not filter by agent ID when not provided.
`agent_workspace_id`	string	No	ID of the workspace to which the agent belongs. When `agent_id` is specified without this parameter, the current workspace is used; only the current workspace or the system workspace can be specified.
`role`	string	No	Filter by message role.
`limit`	integer	No	Single return quantity. `50` when not provided or less than or equal to `0`, up to `200`.
`offset`	integer	No	Returns the offset. `0` when not provided or less than `0`.

Successful response¶

Returns 200 on success. data.items is a saved message on this page. It provides related information and content segmentation according to the session message sequence number.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "msg_01",
        "workspace_id": "ws_01",
        "conversation_id": "conv_01",
        "task_id": "task_01",
        "agent_id": "agent_01",
        "role": "assistant",
        "parts": [
          {
            "kind": "text",
            "text": "分析已完成"
          }
        ],
        "seq": 2,
        "created_at": "2026-01-02T15:04:05Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.items`	object[]	List of messages on this page.
`data.items[].id`	string	Message ID.
`data.items[].workspace_id`	string	ID of the workspace to which the message belongs.
`data.items[].conversation_id`	string	The session ID to which the message belongs.
`data.items[].task_id`	string	Associated task ID; does not return if there is no associated task.
`data.items[].agent_id`	string	Associated agent ID; not returned if there is no associated agent.
`data.items[].manifest_id`	string	Associated runtime manifest ID; not returned if there is no associated manifest.
`data.items[].role`	string	Message role.
`data.items[].parts`	object[]	Message content segments. The fields of each element are determined by the message segment type.
`data.items[].parent_message_id`	string	Parent message ID; does not return if there is no parent message.
`data.items[].seq`	integer	Message sequence number within the session.
`data.items[].created_at`	string	Message creation time, in RFC 3339 format.
`data.total`	integer	The total number of messages that meet the filter conditions.
`data.limit`	integer	The upper limit of the actual return quantity used this time.
`data.offset`	integer	The offset actually used this time.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

{
  "code": 3,
  "message": "会话不存在"
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	Invalid session ID, agent filter parameter, or pagination parameter.	Check path and query parameters.
`404`	`3`（`NOT_FOUND`）	The session does not exist, is not visible, or does not belong to the specified agent scope.	Confirm session ID and agent filters.
`500`	`1`（`INTERNAL`）	The server cannot query messages or generate message display data.	Record the request time and error message and try again.
`503`	`15`（`UNAVAILABLE`）	Session service is temporarily unavailable.	Try again later.

Follow-up operations¶

Use Query session details to read the session’s current display information and active task associations.

Last updated on Sep 3, 2026