Group current conversations by agent¶
Read ordinary chat conversations for the current account in the current workspace, grouped by agent. Groups include only persisted active, chat, visible, unpinned conversations; this is not a complete agent or conversation inventory.
GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/conversations/agent-groups
Before you call this API¶
Set PRODUCT_API_BASE_URL to the product API prefix https://api.moi.matrixorigin.cn/v5; use the corresponding product API URL for a dedicated deployment.
PRODUCT_API_BASE_URL includes the product prefix for the target environment. Prepare your credentials and an authorized WORKSPACE_ID. The path ID must match X-Workspace-ID. Replace example IDs with actual values returned in that environment.
Request¶
curl --get "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/conversations/agent-groups" \
-H "X-API-Key: $PRODUCT_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID"
There are no business query parameters or request body. This action does not parse limit, offset, keyword, surface, or similar filters. Copying conversation-list parameters does not change the group scope.
Groups use both agent_workspace_id and agent_id. There are no pagination fields. total counts groups, not the sum of conversation_count across groups.
Successful response¶
{"code":0,"data":{"items":[{"agent_workspace_id":"workspace-example","agent_id":"agent-example","agent_summary":{"id":"agent-example","workspace_id":"workspace-example","display_name":"示例智能体","available":true},"conversation_count":3,"last_activity_at":"2026-11-12T01:02:03Z"}],"total":1}}
Field |
Type |
Description |
|---|---|---|
data.items |
array |
All groups in this response; an empty array when no results match. |
data.items[].agent_workspace_id |
string |
Agent source workspace. |
data.items[].agent_id |
string |
Agent ID. |
data.items[].agent_summary |
object |
Agent display summary. Prefers the current definition and retains historical display information if none is found. |
data.items[].agent_summary.available |
boolean |
Whether the current summary is marked available. This does not establish successful invocation. |
data.items[].agent_summary.unavailable_reason |
string |
Optional unavailability reason. |
data.items[].conversation_count |
integer |
Number of conversations matching this action’s fixed scope. |
data.items[].last_activity_at |
string |
Latest message time in the group; falls back to conversation creation time when no messages exist. |
data.total |
integer |
Number of groups. |
Sorted by last_activity_at descending, then agent source workspace and agent ID for ties. Historical groups may remain after an agent is archived or deleted; their presence does not imply that the agent can still be invoked.
Continue reading¶
After selecting a group, call the agent conversation list with the same agent_workspace_id and agent_id and explicitly set status=active, purpose=chat, visibility=visible, and pinned=false to match the group count’s scope. Query pinned, archived, and other-purpose conversations separately. An absent group does not prove that no related conversations exist.
Errors¶
Workspace mismatches can return 400, identity or permission failures 401/403, and read or display dependency failures 500/503. A failed group read does not change existing conversations. Read again after resolving the failure.