DescribeInstances - E-MapReduce - Alibaba Cloud Documentation Center

This operation queries Serverless StarRocks instances. You can filter the instances by criteria such as instance name and tags.

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

sr:DescribeInstances

get

*Instance

acs:sr:{#regionId}:{#accountId}:instance/{#InstanceId}

None

Request syntax

POST /webapi/starrocks/describeInstances HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
InstanceName	string	No	The instance name.	starrocks_1
InstanceId	string	No	The instance ID.	c-a0cb1c8ad6d35XXX
PageNumber	integer	No	The page number.	1
PageSize	integer	No	The number of entries per page.	10
RegionId	string	No	The region ID of the instance.	cn-hangzhou
InstanceStatus	string	No	The instance status to filter by. You can specify multiple statuses, separated by commas. Valid values: unpaid paid creating running updating disable deleting scaling_out scaling_in scaling_up scaling_down upgrading modifying_config enable_public_network disable_public_network convert_from_trial_to_official restarting migration_cluster_to_serverless actively_disabled enabling agent_creating agent_scaling_up	running,creating
ResourceGroupId	string	No	The resource group ID.	rg-acfmygmtrcenXXX
Tag	array<object>	No	The list of tags.
	object	No	The tag information.
Key	string	No	The tag key.	k1
Value	string	No	The tag value.	v1

Response elements

Element	Type	Description	Example
	object
HttpStatusCode	integer	The HTTP status code.	200
RequestId	string	The request ID.	32A44F0D-BFF6-5664-999A-218BBDE74XXX
Success	boolean	Indicates whether the request was successful.	false
Total	integer	The total number of instances.	3
ErrCode	string	The error code.	InvalidParams
ErrMessage	string	The error message.	Invalid params: [instance not exists].
Data	array<object>	The query results.
	object	The instance information.
InstanceId	string	The instance ID.	c-d4be777ff5e8cXXX
RegionId	string	The region ID.	cn-hangzhou
InstanceStatus	string	The instance status. Valid values: not_init: The instance is not initialized. unpaid: The instance is pending payment. paid: The payment is made. creating: The instance is being created. creating_failed: The instance failed to be created. created: The instance is created. running: The instance is running. updating: The instance is being upgraded. agent_creating: The agent is being created. agent_scaling_up: The agent is being upgraded. modifying_config: The configurations are being updated. scaling_out: The instance is being scaled out. restarting: The instance is restarting. scaling_in: The instance is being scaled in. scaling_up: The instance is being upgraded. scaling_down: The instance is being downgraded. upgrading: The instance is being upgraded. enable_public_network: The public endpoint is being enabled. disable_public_network: The public endpoint is being disabled. convert_from_trial_to_official: The instance edition is being changed. migration_cluster_to_serverless: The cluster is being migrated. modifying_timezone: The time zone is being modified. switch_az: The primary and secondary zones are being switched. enabling: The instance is being resumed. disable: The instance is unavailable. actively_disabled: The instance is unavailable. deleting: The instance is being deleted. deleting_failed: The instance failed to be deleted. deleted_with_error: The instance is deleted due to a creation failure. deleted: The instance is deleted.	running
InstanceName	string	The instance name.	sr_test_1
PackageType	string	The instance edition. Valid values: trial: Trial Edition. official: Standard Edition.	official
ResourceGroupId	string	The resource group ID.	rg-acfmytyuofb****
Tags	array<object>	The tags attached to the instance.
	object	The tag information.
Key	string	The tag key.	k1
Value	string	The tag value.	v1
BeginTime	integer	The time when the cluster was created.	1733292921000
ExpireTime	integer	The time when the cluster expires.	4889001600000
RunningTime	integer	The duration for which the cluster has been running. Unit: seconds.	3645445
VSwitches	array<object>	The list of vSwitches.
	object	The vSwitch information.
ZoneId	string	The zone ID.	cn-hangzhou-i
VswId	string	The vSwitch ID.	vsw-bp1p0mldwx5av55v0xXXX
Primary	boolean	Indicates whether the vSwitch is the primary vSwitch.	true
PayType	string	The billing method: prePaid: subscription. postPaid: pay-as-you-go.	postPaid
Version	string	The cluster version.	3.2
VpcId	string	The VPC ID.	vpc-bp1rbvag1cafkj4prwXXX
RunMode	string	The running mode of the cluster: shared_nothing: all-in-one. shared_data: storage-compute separation. lakehouse: data lake analytics.	shared_nothing
MaintainablePeriod	string	The maintenance window of the instance. Valid values: 00:00-06:00 06:00-07:00 07:00-08:00 08:00-09:00 09:00-10:00 10:00-11:00 11:00-12:00 12:00-13:00 13:00-14:00 14:00-15:00 15:00-16:00 16:00-17:00 17:00-18:00 18:00-19:00 19:00-20:00 20:00-21:00 21:00-22:00 22:00-23:00 23:00-24:00	00:00-06:00
MinorVersion	string	The minor version number.	3.2.11-1.79-1.6.5
EnableAutoMinorVersionUpgrade	boolean	Indicates whether automatic minor version upgrades are enabled.	true
EnabledAuditLoader	boolean	Indicates whether the audit plugin is enabled.	true
MonitorType	string	The type of the monitoring service.	cms
Architecture	string	The instance architecture. Valid values: onEci: deployed on ECI. onECS: deployed on ECS. onBareMetal: deployed on a bare metal resource pool.	onECS
AclId	string	The ID of the network access control list (ACL).	acl-bp1xc6b9vs013jjtp****
SgId	string	The security group ID.	sg-8vbaz2etr66a62b9****
OssLocation	string	The OSS URL.	oss://sr-c-****
SecurityGroupManaged	boolean	Indicates whether the security group is a managed security group.	true
IsolateLeader	boolean	Indicates whether read/write splitting is enabled. If this parameter is set to true, the leader FE node processes write requests, and the other FE nodes process read requests.	true
EnableSSL	boolean	Indicates whether SSL is enabled.	true
Encrypted	boolean	Indicates whether encryption is enabled.	true
KmsKeyId	string	The ID of the KMS key.	rewqfds****

Examples

Success response

JSON format

{
  "HttpStatusCode": 200,
  "RequestId": "32A44F0D-BFF6-5664-999A-218BBDE74XXX\n",
  "Success": false,
  "Total": 3,
  "ErrCode": "InvalidParams\n",
  "ErrMessage": "Invalid params: [instance not exists].",
  "Data": [
    {
      "InstanceId": "c-d4be777ff5e8cXXX",
      "RegionId": "cn-hangzhou",
      "InstanceStatus": "running",
      "InstanceName": "sr_test_1",
      "PackageType": "official",
      "ResourceGroupId": "rg-acfmytyuofb****",
      "Tags": [
        {
          "Key": "k1",
          "Value": "v1"
        }
      ],
      "BeginTime": 1733292921000,
      "ExpireTime": 4889001600000,
      "RunningTime": 3645445,
      "VSwitches": [
        {
          "ZoneId": "cn-hangzhou-i",
          "VswId": "vsw-bp1p0mldwx5av55v0xXXX",
          "Primary": true
        }
      ],
      "PayType": "postPaid",
      "Version": "3.2",
      "VpcId": "vpc-bp1rbvag1cafkj4prwXXX",
      "RunMode": "shared_nothing",
      "MaintainablePeriod": "00:00-06:00",
      "MinorVersion": "3.2.11-1.79-1.6.5",
      "EnableAutoMinorVersionUpgrade": true,
      "EnabledAuditLoader": true,
      "MonitorType": "cms",
      "Architecture": "onECS",
      "AclId": "acl-bp1xc6b9vs013jjtp****",
      "SgId": "sg-8vbaz2etr66a62b9****",
      "OssLocation": "oss://sr-c-****",
      "SecurityGroupManaged": true,
      "IsolateLeader": true,
      "EnableSSL": true,
      "Encrypted": true,
      "KmsKeyId": "rewqfds****"
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.