Query the list of agents

Lists the agents whose current identity is readable in the workspace. It can be filtered by status, keywords and display scenarios, and read in sections through paging parameters.

GET https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents

Preparation before calling

Prepare a personal access token and target workspace ID that has 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: The workspace ID to query, passed through the X-Workspace-ID Header and as workspace_id in the path.

Request example

curl --get "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "surface=agent_chat" \
  --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
status	string	No	Filter by agent status.
query	string	No	Filter by keyword.
surface	string	No	Display scene; only agent_chat is accepted.
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.

The returned results have been filtered by the current identity’s agent read permissions.

Successful response

Returns 200 on success. data.items is the agent that can be read on this page, and data.total is the total number after filtering.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "agent_01",
        "workspace_id": "ws_01",
        "schema_version": 1,
        "name": "销售助手",
        "instruction": {
          "system_prompt": "分析销售数据"
        },
        "runtime": {
          "provider": "matrixone",
          "profile": "default"
        },
        "status": "active",
        "version": 1,
        "source_type": "custom",
        "created_at": "2026-01-15T10:00:00Z",
        "updated_at": "2026-01-15T10:00:00Z"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.items	object[]	List of agents on this page.
data.items[].id	string	Agent ID and workspace ID.
data.items[].workspace_id	string	Agent ID and workspace ID.
data.items[].schema_version	integer	Agent metadata structure version.
data.items[].name	string	Agent name and description; will not be returned if no description is set.
data.items[].description	string	Agent name and description; will not be returned if no description is set.
data.items[].icon	string	Display icon; does not return if not set.
data.items[].display_tags	string[]	Label used for display; does not return if not set.
data.items[].instruction	object	Command configuration.
data.items[].runtime	object	Run target containing provider, profile, and optionally config.
data.items[].model	object	Model configuration and resource binding; does not return if not set.
data.items[].binding	object	Model configuration and resource binding; does not return if not set.
data.items[].policy_refs	object	Policy and workflow reference; not returned if not set.
data.items[].workflow_refs	object	Policy and workflow reference; not returned if not set.
data.items[].lifecycle	object	Life cycle information; does not return if not set.
data.items[].status	string	Agent status and resource version.
data.items[].version	integer	Agent status and resource version.
data.items[].source_type	string	Source type and source reference; not returned when source reference is not set.
data.items[].source_ref	string	Source type and source reference; not returned when source reference is not set.
data.items[].metadata	object	Extended metadata; not returned if not set.
data.items[].created_by	string	Creator ID; does not return if not set.
data.items[].updated_by	string	Last updater ID; does not return if not set.
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 agents that meet the filter conditions and can be read by the current identity.
data.limit	integer	The paging value actually used this time.
data.offset	integer	The paging value 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": "invalid agent resource request"
}

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	surface is not agent_chat, or the workspace and paging parameters are invalid.	Check path and query parameters.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have read permission to the workspace.	Use an authorized identity, or contact the administrator for authorization.
503	15（UNAVAILABLE）	The agent resource service or its authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Use data.items[].id to call Query agent details, or call Query the agent version to view the version status.

Last updated on Sep 6, 2026