List Agents

Paginated query of Agents under the current tenant.

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
}