List Agents

Prerequisites

Obtain an Alibaba Cloud Model Studio API Key and workspace ID first. For authentication, see API Authentication. This is a read operation and requires only an API Key.

Endpoint

POST /api/v1/indices/rag/app/list Paginated query of the Agent list for a specified scene, with support for filtering by status, name, Agent ID, associated knowledge base Pipeline ID, and other conditions.

Request body

Field	Required	Type	Description
`agent_scene`	Yes	string	Agent scene: `chat` (knowledge Q&A) or `search` (knowledge retrieval).
`agent_status`	No	string	Filter by status: `draft` / `deployed` (includes `edited`) / `deleted`.
`agent_name`	No	string	Fuzzy search by name.
`agent_id`	No	string	Exact match by Agent ID.
`pipeline_id`	No	string	Filter by associated knowledge base Pipeline ID.
`page_number`	No	integer	Page number, default 1.
`page_size`	No	integer	Number of items per page, default 10, maximum 100.

Request example

curl -X POST "$BASE_URL/api/v1/indices/rag/app/list" \
  -H "Authorization: Bearer $BAILIAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_scene": "chat",
    "page_number": 1,
    "page_size": 20
}'

BASE_URL is https://{workspace_id}.cn-beijing.maas.aliyuncs.com ({workspace_id} is the workspace ID), and BAILIAN_API_KEY is your Alibaba Cloud Model Studio API Key.

Response example

Returns 200 on success.

{
  "request_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
  "status_code": 200,
  "code": "Success",
  "message": "",
  "status": "SUCCESS",
  "success": true,
  "data": {
    "page_number": 1,
    "page_size": 20,
    "total_count": 2,
    "rows": [
      {
        "agent_id": "aid-8f3a1b2c4d5e6f70",
        "agent_name": "Customer Service Q&A Assistant",
        "agent_scene": "chat",
        "agent_status": "deployed",
        "agent_version": "2",
        "create_time": "2026-07-10T14:30:00",
        "modify_time": "2026-07-15T09:15:00",
        "pipeline_list": [
          {
            "pipeline_id": "pipeline-xxxxxx",
            "pipeline_name": "Product Documentation Knowledge Base"
          }
        ]
      },
      {
        "agent_id": "aid-1a2b3c4d5e6f7a8b",
        "agent_name": "Technical Documentation Search Assistant",
        "agent_scene": "chat",
        "agent_status": "draft",
        "agent_version": "beta",
        "create_time": "2026-07-12T10:00:00",
        "modify_time": "2026-07-12T10:00:00",
        "pipeline_list": [
          {
            "pipeline_id": "pipeline-yyyyyy",
            "pipeline_name": "Technical Documentation Knowledge Base"
          },
          {
            "pipeline_id": "pipeline-zzzzzz",
            "pipeline_name": "FAQ Knowledge Base"
          }
        ]
      }
    ]
  }
}

Response fields

Field	Type	Description
`request_id`	string	Unique request identifier. Provide this ID when troubleshooting issues.
`status_code`	integer	HTTP status code.
`code`	string	Response code. `Success` on success.
`message`	string	Informational message.
`status`	string	Request status: `SUCCESS` or `FAILED`.
`success`	boolean	Whether the request succeeded.
`data.page_number`	integer	Current page number.
`data.page_size`	integer	Number of items per page.
`data.total_count`	integer	Total number of records.
`data.rows`	array<object>	List of Agents. See the element table below.

data.rows[] elements

Field	Type	Description
`agent_id`	string	Agent ID.
`agent_name`	string	Agent name.
`agent_scene`	string	Agent scene: `chat` or `search`.
`agent_status`	string	Agent status: `draft`, `deployed`, `edited`, `deleted`.
`agent_version`	string	Current Agent version number.
`create_time`	string	Creation time (ISO 8601).
`modify_time`	string	Modification time (ISO 8601).
`pipeline_list`	array<object>	List of associated knowledge bases. See the element table below.

data.rows[].pipeline_list[] elements

Field	Type	Description
`pipeline_id`	string	Knowledge base Pipeline ID.
`pipeline_name`	string	Knowledge base name.

Error codes

HTTP status code	Error code	Description
400	`Index.InvalidParameter`	Invalid request parameters. Please check that all parameters are complete and correctly typed.

Error response example:

{
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status_code": 400,
  "code": "Index.InvalidParameter",
  "message": "Invalid request parameters. Please check that all parameters are complete and correctly typed.",
  "status": "FAILED",
  "success": false
}

​Prerequisites

​Endpoint

​Request body

​Request example

​Response example

​Response fields

​Error codes