Query session list

Query the visible sessions in the workspace. It can be filtered by agent, status, purpose or top status, and can be read in sections through paging parameters.

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

Preparation before calling

Prepare a personal access token and target workspace ID that has access to the target workspace. If you need to filter by agent, first obtain the agent ID.

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.

• $AGENT_ID: Optional agent filter ID.

Request example

curl --get "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/conversations" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "agent_id=$AGENT_ID" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0"

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	Current workspace ID, must be consistent with X-Workspace-ID.

Query parameters

Parameters	Type	Is it required	Description
agent_id	string	No	Only return sessions for the specified agent.
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.
status	string	No	Filter by session status.
purpose	string	No	Filter by session purpose, can be chat or workflow.
pinned	boolean	No	If it is true or 1, only the pinned conversations will be returned; if it is other values, unpinned conversations will be filtered.
visibility	string	No	Accepts only visible; only returns visible sessions if not provided.
parent_conversation_id	string	No	Filter by parent session ID.
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 the session of this page, data.total is the total number of filter results, data.limit and data.offset are the paging values ​​actually used this time.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "conv_01",
        "workspace_id": "ws_01",
        "agent_workspace_id": "ws_01",
        "agent_id": "agent_01",
        "agent_summary": {
          "id": "agent_01",
          "display_name": "销售分析助手",
          "available": true
        },
        "title": "销售分析",
        "status": "active",
        "purpose": "chat",
        "visibility": "visible",
        "pinned": false,
        "created_at": "2026-01-02T15:04:05Z",
        "updated_at": "2026-01-02T15:04:05Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.items	object[]	Session list on this page.
data.items[].id	string	Session ID.
data.items[].workspace_id	string	ID of the workspace to which the session belongs.
data.items[].agent_workspace_id	string	ID of the workspace to which the agent belongs.
data.items[].agent_id	string	Agent ID.
data.items[].agent_summary	object	Summary of agent display.
data.items[].title	string	Session title; not returned if not set.
data.items[].status	string	Session status.
data.items[].purpose	string	Session use.
data.items[].visibility	string	Session visibility.
data.items[].pinned	boolean	Whether to pin it to the top.
data.items[].head_message_id	string	Recent message ID; does not return if there is no message.
data.items[].active_task_id	string	Current active task ID; does not return if there is no active task.
data.items[].last_message_at	string	Last message time; does not return if there is no message.
data.items[].created_at	string	Creation and last update times, in RFC 3339 format.
data.items[].updated_at	string	Creation and last update times, in RFC 3339 format.
data.total	integer	The total number of sessions that meet the filter criteria.
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": 2,
  "message": "请求参数无效",
  "details": {
    "cause": "invalid runtime conversation"
  }
}

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	Invalid agent ID, workspace ID, purpose, visibility, or paging parameters.	Check query parameters; visibility can only be visible.
500	1（INTERNAL）	The server cannot query the session or generate session display information.	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 the returned data.items[].id to call Query session details or Query session messages.

Last updated on Sep 3, 2026