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.

Last updated on