DescribeAgenticDBClusters - PolarDB - Alibaba Cloud Documentation Center

Queries the list of Agentic Database clusters.

Operation description

This operation supports filtering and returning the list of related model operators based on the RelativeDBClusterId and KubeType parameters.
Note: Ensure that the RelativeDBClusterId provided in the request matches an existing PolarDB instance ID. Otherwise, data cannot be retrieved correctly.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

polardb:DescribeAgenticDBClusters

list

*All Resource

*

None

Request syntax

GET  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID.	cn-hangzhou
DBClusterIds	string	No	The cluster ID. Separate multiple cluster IDs with commas (,).	pc-**************
AgenticDbClusterIds	string	No	The Agentic cluster ID. Separate multiple cluster IDs with commas (,).	pagc-**************
DBClusterDescription	string	No	The cluster description. Fuzzy match is supported.	pc-****************
DBClusterStatus	string	No	The cluster status.	Running
PageSize	integer	No	The number of entries per page. Valid values: 30, 50, and 100. Default value: 30.	30
PageNumber	integer	No	The page number.	1
ResourceGroupId	string	No	The resource group ID.	rg-************
Tag	array<object>	No	The tags.
	object	No	The tags.
Value	string	No	The tag value that corresponds to the tag key.	testValueData
Key	string	No	The tag key. You can use tags to filter clusters. You can specify up to 20 tags. The number n for each tag pair must be unique and must be a consecutive integer that starts from 1. The Tag.n.Key parameter is paired with the Tag.n.Value parameter.	type
MaxResults	integer	No	The maximum number of entries to return. Default value: 10.	10
NextToken	string	No	The pagination token. Set this parameter to the NextToken value returned in the previous API call. If there is no next query, do not specify this parameter.	212db86sca4384811e0b5e8707e******

Response elements

Element	Type	Description	Example
	object	Schema of Response
TotalRecordCount	integer	The total number of records.	1
PageRecordCount	integer	The number of clusters on the current page.	1
RequestId	string	The request ID.	CDB3258F-B5DE-43C4-8935-CBA0CA******
PageNumber	integer	The page number.	1
Items	array<object>	The cluster list.
	array<object>	The SSL connection information.
DBClusterId	string	The cluster ID.	pc-xxxxxx
RegionId	string	The region ID.	cn-hangzhou
ZoneId	string	The zone ID.	cn-hangzhou-i
DBClusterStatus	string	The cluster status.	Running
CreateTime	string	The time when the cluster was created. The time is in the ISO 8601 format in UTC (format: YYYY-MM-DDTHH:mm:ssZ).	2020-08-14T05:58:42Z
DBClusterDescription	string	The cluster description.	ocpx
DBType	string	The database engine type.	MySQL
DBVersion	string	The database engine version.	8.0
Category	string	The cluster edition. Valid values: Normal: Cluster Edition Basic: Single Node Edition Archive: X-Engine Edition NormalMultimaster: Multi-master Cluster (Database/Table)	Normal
ServerlessType	string	The serverless type. A return value of AgileServerless indicates that the cluster is a serverless cluster.	AgileServerless
PayType	string	The billing method. Valid values: Postpaid: pay-as-you-go. Prepaid: subscription.	Postpaid
StorageType	string	The storage type. Valid values: essdpl0 essdpl1 essdpl2 essdpl3	city_redundancy
StorageUsed	integer	The storage usage of the cluster. Unit: bytes.	3009413120
ScaleMin	string	The minimum value: 0 to 32 PCUs. The minimum value must be less than or equal to the maximum value. Unit: PCU.	1
ScaleMax	string	The maximum value: 1 to 32 PCUs. Unit: PCU.	9
VpcId	string	The ID of the virtual private cloud (VPC) in which the endpoint resides.	vpc-****************
VswitchId	string	The vSwitch ID.	vsw-**************
Expired	string	Indicates whether the cluster has expired. Valid values: true false Note This parameter is returned only for clusters whose billing method is Prepaid (subscription).	false
LockMode	string	The lock status of the cluster. Valid values: Unlock: Normal. ManualLock: manually locked. LockByExpiration: automatically locked due to cluster expiration.	Unlock
ExpireTime	string	The expiration time of the cluster. Note A specific value is returned only for clusters whose billing method is Prepaid (subscription). An empty value is returned for Postpaid (pay-as-you-go) clusters. The time is in the ISO 8601 format in UTC (format: YYYY-MM-DDTHH:mm:ssZ).	2025-06-25T09:37:10Z
Tags	array<object>	The tag key. You can use tags to filter clusters. You can specify up to 20 tags. The number n for each tag pair must be unique and must be a consecutive integer that starts from 1. The Tag.n.Key parameter is paired with the Tag.n.Value parameter.
	object	The tag key. You can use tags to filter clusters. You can specify up to 20 tags. The number n for each tag pair must be unique and must be a consecutive integer that starts from 1. The Tag.n.Key parameter is paired with the Tag.n.Value parameter.
Value	string	The tag value.	testValueData
Key	string	The tag key.	MySQL
AgenticDbClusterId	string	The Agentic cluster ID.	pagc-**************
AgenticDbClusterDescription	string	The Agentic cluster description.	pagc-**************
NextToken	string	The pagination token. Set this parameter to the NextToken value returned in the previous API call. If there is no next query, do not specify this parameter.	212db86sca4384811e0b5e8707e******
MaxResults	integer	The maximum number of entries to return. Default value: 10.	10

Examples

Success response

JSON format

{
  "TotalRecordCount": 1,
  "PageRecordCount": 1,
  "RequestId": "CDB3258F-B5DE-43C4-8935-CBA0CA******",
  "PageNumber": 1,
  "Items": [
    {
      "DBClusterId": "pc-xxxxxx",
      "RegionId": "cn-hangzhou",
      "ZoneId": "cn-hangzhou-i",
      "DBClusterStatus": "Running",
      "CreateTime": "2020-08-14T05:58:42Z",
      "DBClusterDescription": "ocpx",
      "DBType": "MySQL",
      "DBVersion": "8.0",
      "Category": "Normal",
      "ServerlessType": "AgileServerless",
      "PayType": "Postpaid",
      "StorageType": "city_redundancy",
      "StorageUsed": 3009413120,
      "ScaleMin": "1",
      "ScaleMax": "9",
      "VpcId": "vpc-****************",
      "VswitchId": "vsw-**************",
      "Expired": "false",
      "LockMode": "Unlock",
      "ExpireTime": "2025-06-25T09:37:10Z",
      "Tags": [
        {
          "Value": "testValueData",
          "Key": "MySQL"
        }
      ],
      "AgenticDbClusterId": "pagc-**************",
      "AgenticDbClusterDescription": "pagc-**************"
    }
  ],
  "NextToken": "212db86sca4384811e0b5e8707e******",
  "MaxResults": 10
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.