All Products
Search

This Product

    ApsaraMQ for RocketMQ:GetInstance

    Document Center

    ApsaraMQ for RocketMQ:GetInstance

    Last Updated:Apr 01, 2026

    Retrieves the details of a specified instance.

    Operation description

    Important Alibaba Cloud OpenAPI is a management API for managing and querying Alibaba Cloud resources. Use this API for the management path only. Do not rely on it within the core data path for message transport, as this may introduce risks.

    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

    rocketmq:GetInstance

    get

    *Instance

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

    		 None None

    Request syntax

    GET /instances/{instanceId} HTTP/1.1

    Path Parameters

    Parameter

    Type

    Required

    Description

    Example
    instanceId

    string

    Yes

    The ID of the instance to query.

    rmq-cn-7e22ody****

    Request parameters

    Parameter

    Type

    Required

    Description

    Example

    No parameters required.

    Response elements

    Element

    Type

    Description

    Example

    object

    The data returned for the request.

    requestId

    string

    The request ID. Each request has a unique ID. You can use the request ID to troubleshoot issues.

    05AB7FBD-F1D3-5D87-BF78-BD782249****
    success

    boolean

    Indicates whether the request was successful.

    true
    data

    object

    The details of the instance.

    regionId

    string

    The region ID of the instance.

    cn-hangzhou
    instanceId

    string

    The instance ID.

    rmq-cn-7e22ody****
    instanceName

    string

    The instance name.

    test instance
    status

    string

    The instance status.

    Valid values:

    • RELEASED: The instance has been released.

    • RUNNING: The instance is running.

    • STOPPED: The instance is stopped.

    • CHANGING: The instance is undergoing configuration changes.

    • CREATING: The instance is being created.

    Valid values:

    • RELEASED :

      Released

    • RUNNING :

      Running

    • STOPPED :

      Stopped

    • CHANGING :

      Changing

    • CREATING :

      Creating

    RUNNING
    startTime

    string

    The time when the instance was started.

    2022-08-01 00:00:00
    expireTime

    string

    The expiration time of the instance.

    2022-09-01 00:00:00
    releaseTime

    string

    The time when the instance was released.

    2022-09-07 00:00:00
    userId

    string

    The user ID of the instance owner.

    111111111111111
    bid

    string

    The business ID (BID) of the commodity.

    26842
    commodityCode

    string

    The commodity code of the ApsaraMQ for RocketMQ 5.0 instance, such as ons_rmqsub_public_cn.

    ons_rmqsub_public_cn
    serviceCode

    string

    The service code of the instance. The value for ApsaraMQ for RocketMQ is rmq.

    rmq
    seriesCode

    string

    The primary series code of the instance. For more information about the differences between instance editions, see Product selection.

    Valid values:

    • standard: Standard Edition

    • ultimate: Platinum Edition

    • professional: Professional Edition

    • shared: Shared Edition

    • dedicated: Exclusive Edition

    Valid values:

    • standard :

      Standard Edition

    • ultimate :

      Platinum Edition

    • professional :

      Professional Edition

    standard
    subSeriesCode

    string

    The sub-series code of the instance. For more information about the differences between instance editions, see Product selection.

    Valid values:

    • cluster_ha: High-availability Edition

    • single_node: Single Node Edition

    • serverless: Serverless Edition

    Valid values:

    • cluster_ha :

      High-availability Edition

    • single_node :

      Single Node Edition

    cluster_ha
    paymentType

    string

    The billing method of the instance.

    Valid values:

    • PayAsYouGo: pay-as-you-go

    • Subscription: subscription

    Valid values:

    • PayAsYouGo :

      pay-as-you-go

    • Subscription :

      subscription

    Subscription
    remark

    string

    The instance remark.

    This is remark for instance.
    networkInfo

    object

    The network information.

    vpcInfo

    object

    The VPC information.

    vpcId

    string

    The VPC ID associated with the instance.

    vpc-uf6of9452b2pba82c****
    vSwitchId deprecated

    string

    The vSwitch ID associated with the instance.

    Important This field is deprecated. Use the vSwitches field instead. For compatibility, this field returns only one vSwitch.

    vsw-uf6gwtbn6etadpvz7****
    vSwitches

    array<object>

    The list of vSwitches associated with the instance.

    object

    vSwitchId

    string

    The vSwitch ID.

    vsw-uf6gwtbn6etadpvz7****
    zoneId

    string

    The zone ID.

    cn-hangzhou
    securityGroupIds

    string

    The security group ID.

    sg-hp35r2hc3a3sv8q2sb16
    endpoints

    array<object>

    A list of endpoints for the instance.

    object

    Details of a single endpoint.

    endpointType

    string

    The endpoint type of the instance.

    Valid values:

    • TCP_VPC :

      VPC endpoint

    • TCP_INTERNET :

      public endpoint

    TCP_INTERNET
    endpointUrl

    string

    The endpoint of the instance.

    rmq-cn-c4d2tbk****-vpc.cn-hangzhou.rmq.aliyuncs.com:8080
    ipWhitelist

    array

    The IP address whitelist for public network access. You can configure an IP address whitelist only for public endpoints. This feature is not supported for VPC endpoints.

    • If no IP address whitelist is configured, any IP address can access the ApsaraMQ for RocketMQ server over the public network.

    • If an IP address whitelist is configured, only IP addresses in the whitelist can access the ApsaraMQ for RocketMQ server over the public network.

    This parameter is deprecated. We recommend that you use the internetInfo.ipWhitelist parameter instead.

    192.168.x.x/24

    string

    An IP address in the whitelist for public network access.

    192.168.x.x/24
    endpointId

    string

    The ID of the associated PrivateLink endpoint.

    ep-bpxxx
    internetInfo

    object

    The public network information of the instance.

    internetSpec

    string

    Indicates whether public network access is enabled.

    Valid values:

    • enable: Enabled

    • disable: Disabled

    By default, instances are accessible only within a VPC. Enabling public network access incurs charges for outbound public bandwidth. For more information, see Public network access fees.

    Valid values:

    • enable :

      Enabled

    • disable :

      Disabled

    enable
    flowOutType

    string

    The billing method for public network traffic.

    Valid values:

    • payByBandwidth: The pay-by-bandwidth billing method. This value is returned if public network access is enabled.

    • uninvolved: Not applicable. This value is returned if public network access is disabled.

    Valid values:

    • payByBandwidth :

      pay-by-bandwidth

    • uninvolved :

      not applicable

    payByBandwidth
    flowOutBandwidth

    integer

    The public bandwidth, in Mbit/s.

    1
    ipWhitelist

    array

    The IP address whitelist for public network access.

    • If no IP address whitelist is configured, any IP address can access the ApsaraMQ for RocketMQ server over the public network.

    • If an IP address whitelist is configured, only IP addresses in the whitelist can access the ApsaraMQ for RocketMQ server over the public network.

    string

    An IP address in the whitelist for public network access.

    192.168.x.x/24
    accountInfo

    object

    The account information.

    username

    string

    The username for the instance. If you access the instance over the public network, you must configure the username and password in your SDK code for identity verification.

    6W0xz2uPfiwp****
    instanceQuotas

    array<object>

    A list of quota details for the instance.

    object

    The details of a specific quota.

    quotaName

    string

    The name of the instance quota.

    Valid value:

    • TOPIC_COUNT: the topic creation quota for the instance.

    Valid values:

    • TOPIC_COUNT :

      The topic creation quota for the instance.

    TOPIC_COUNT
    usedCount

    number

    The amount of the quota that has been used.

    10
    freeCount

    number

    The remaining amount of the quota.

    20
    totalCount

    number

    The total amount of the quota.

    100
    createTime

    string

    The time when the instance was created.

    2022-08-01 00:00:00

    updateTime

    string

    The time when the instance was last updated.

    2022-08-02 00:00:00

    extConfig deprecated

    object

    The extended configurations. This parameter is deprecated. We recommend that you use parameters such as productInfo, internetInfo, and aclInfo instead.

    aclType

    string

    The authentication type of the instance.

    Valid value:

    • default: Intelligent identity verification

    Valid values:

    • default :

      intelligent identity verification

    default
    sendReceiveRatio

    number

    The ratio of sent messages to received messages.

    0.5
    autoScaling

    boolean

    Specifies whether elastic scaling is enabled.

    Valid values:

    • true: Enabled

    • false: Disabled

    This parameter takes effect only if the instance supports elastic scaling (when supportAutoScaling is true).

    Valid values:

    • true :

      Enabled

    • false :

      Disabled

    true
    messageRetentionTime

    integer

    The message retention period, in hours.

    For the value range, see the "Message retention period" section in the "Resource quotas" topic of Limits.

    ApsaraMQ for RocketMQ provides serverless message storage and charges you for the actual storage space that you use. You can change the message retention period to manage storage capacity. For more information, see Storage fees.

    72
    supportAutoScaling

    boolean

    Indicates whether the instance supports elastic scaling.

    Valid values:

    • true: Supported

    • false: Not supported

    After you enable elastic scaling, ApsaraMQ for RocketMQ allows the instance to exceed the TPS limit of the base specifications within a specific range. You are charged for the TPS that exceeds the base specifications. For more information, see Computing capacity fees.

    Note

    Only specific instance editions support elastic scaling. For more information about the supported instance editions, see Instance types.

    Valid values:

    • true :

      Supported

    • false :

      Not supported

    true
    internetSpec

    string

    Indicates whether public network access is enabled.

    Valid values:

    • enable: Enabled

    • disable: Disabled

    By default, instances are accessible only within a VPC. Enabling public network access incurs charges for outbound public bandwidth. For more information, see Public network access fees.

    Valid values:

    • enable :

      Enabled

    • disable :

      Disabled

    enable
    flowOutType

    string

    The billing method for public network traffic.

    Valid values:

    • payByTraffic: Pay-by-data-transfer

    • payByBandwidth: Pay-by-bandwidth

    • uninvolved: Not applicable

    Valid values:

    • payByTraffic :

      pay-by-data-transfer

    • payByBandwidth :

      pay-by-bandwidth

    • uninvolved :

      not applicable

    payByBandwidth
    flowOutBandwidth

    integer

    The public bandwidth, in Mbit/s.

    10
    msgProcessSpec

    string

    The computing specification for message sending and receiving. For more information about the maximum TPS for message sending and receiving, see Instance types.

    rmq.s2.2xlarge
    resourceGroupId

    string

    The resource group ID.

    rg-acfm3tmjruyribi
    productInfo

    object

    The extended configurations of the instance.

    msgProcessSpec

    string

    The computing specification for message sending and receiving. For more information about the maximum TPS for message sending and receiving, see Instance types.

    rmq.s2.2xlarge
    sendReceiveRatio

    number

    The ratio of sent messages to received messages.

    0.5
    autoScaling

    boolean

    Specifies whether elastic scaling is enabled.

    Valid values:

    • true: Enabled

    • false: Disabled

    This parameter takes effect only if the instance supports elastic scaling (when supportAutoScaling is true).

    Valid values:

    • true :

      Enabled

    • false :

      Disabled

    true
    messageRetentionTime

    integer

    The message retention period, in hours.

    For the value range, see the "Message retention period" section in the "Resource quotas" topic of Limits.

    ApsaraMQ for RocketMQ provides serverless message storage and charges you for the actual storage space that you use. You can change the message retention period to manage storage capacity. For more information, see Storage fees.

    72
    supportAutoScaling

    boolean

    Indicates whether the instance supports elastic scaling.

    Valid values:

    • true: Supported

    • false: Not supported

    After you enable elastic scaling, ApsaraMQ for RocketMQ allows the instance to exceed the TPS limit of the base specifications within a specific range. You are charged for the TPS that exceeds the base specifications. For more information, see Computing capacity fees.

    Note

    Only specific instance editions support elastic scaling. For more information about the supported instance editions, see Instance types.

    Valid values:

    • true :

      Supported

    • false :

      Not supported

    true
    traceOn

    boolean

    Specifies whether the message trace feature is enabled.

    • true: Enabled

    • false: Disabled

    This parameter is ignored. The message trace feature is enabled by default regardless of the value of this parameter.

    true
    storageEncryption

    boolean

    Indicates whether storage encryption is enabled.

    false
    storageSecretKey

    string

    The secret key for storage encryption.

    xxxxx
    capacityType

    string

    The capacity mode.

    • provisioned: provisioned capacity and elastic scaling

    • ondemand: on-demand

    Valid values:

    • provisioned :

      provisioned capacity and elastic scaling

    • ondemand :

      on-demand

    provisioned
    provisionedCapacity

    integer

    The provisioned capacity.

    3000
    drReplicationMode

    string

    async_cross_az
    aclInfo

    object

    The access control information.

    aclTypes

    array

    The list of authentication types for the instance.

    string

    The authentication type of the instance.

    Valid values:

    • default :

      Intelligent identity verification

    • apache_acl :

      ACL-based identity verification

    default
    defaultVpcAuthFree

    boolean

    Specifies whether authentication-free access from within the VPC is enabled.

    Valid values:

    • true :

      Enabled

    • false :

      Disabled

    true
    aclType deprecated

    string

    The authentication type of the instance. This parameter is deprecated. We recommend that you use the aclTypes parameter instead.

    Valid values:

    • default :

      Intelligent identity verification

    • apache_acl :

      ACL-based identity verification

    default
    software

    object

    The software information of the instance.

    softwareVersion

    string

    The software version.

    5.0-rmq-20230619-1
    maintainTime

    string

    The maintenance window.

    02:00-06:00
    upgradeMethod

    string

    The upgrade method.

    Valid values:

    • auto: Automatic

    • manual: Manual

    Valid values:

    • auto :

      Automatic

    • maunal :

      Manual

    auto
    topicCount

    integer

    The number of topics.

    10
    groupCount

    integer

    The number of consumer groups.

    10
    tags

    array<object>

    The list of resource tags.

    object

    The resource tag.

    key

    string

    The key of the resource tag.

    key
    value

    string

    The value of the resource tag.

    value
    code

    string

    The error code.

    MissingInstanceId
    message

    string

    The error message.

    Parameter instanceId is mandatory for this action .
    httpStatusCode

    integer

    The HTTP status code.

    400
    dynamicCode

    string

    The dynamic error code.

    InstanceId
    dynamicMessage

    string

    The dynamic error message.

    instanceId

    Examples

    Success response

    JSON format

    {
  "requestId": "05AB7FBD-F1D3-5D87-BF78-BD782249****",
  "success": true,
  "data": {
    "regionId": "cn-hangzhou",
    "instanceId": "rmq-cn-7e22ody****",
    "instanceName": "test instance",
    "status": "RUNNING",
    "startTime": "2022-08-01 00:00:00",
    "expireTime": "2022-09-01 00:00:00",
    "releaseTime": "2022-09-07 00:00:00",
    "userId": "111111111111111",
    "bid": "26842",
    "commodityCode": "ons_rmqsub_public_cn",
    "serviceCode": "rmq",
    "seriesCode": "standard",
    "subSeriesCode": "cluster_ha",
    "paymentType": "Subscription",
    "remark": "This is remark for instance.",
    "networkInfo": {
      "vpcInfo": {
        "vpcId": "vpc-uf6of9452b2pba82c****",
        "vSwitchId": "vsw-uf6gwtbn6etadpvz7****",
        "vSwitches": [
          {
            "vSwitchId": "vsw-uf6gwtbn6etadpvz7****",
            "zoneId": "cn-hangzhou"
          }
        ],
        "securityGroupIds": "sg-hp35r2hc3a3sv8q2sb16"
      },
      "endpoints": [
        {
          "endpointType": "TCP_INTERNET",
          "endpointUrl": "rmq-cn-c4d2tbk****-vpc.cn-hangzhou.rmq.aliyuncs.com:8080",
          "ipWhitelist": [
            "192.168.x.x/24"
          ],
          "endpointId": "ep-bpxxx"
        }
      ],
      "internetInfo": {
        "internetSpec": "enable",
        "flowOutType": "payByBandwidth",
        "flowOutBandwidth": 1,
        "ipWhitelist": [
          "192.168.x.x/24"
        ]
      }
    },
    "accountInfo": {
      "username": "6W0xz2uPfiwp****"
    },
    "instanceQuotas": [
      {
        "quotaName": "TOPIC_COUNT",
        "usedCount": 10,
        "freeCount": 20,
        "totalCount": 100
      }
    ],
    "createTime": "2022-08-01 00:00:00 ",
    "updateTime": "2022-08-02 00:00:00 ",
    "extConfig": {
      "aclType": "default",
      "sendReceiveRatio": 0.5,
      "autoScaling": true,
      "messageRetentionTime": 72,
      "supportAutoScaling": true,
      "internetSpec": "enable",
      "flowOutType": "payByBandwidth",
      "flowOutBandwidth": 10,
      "msgProcessSpec": "rmq.s2.2xlarge"
    },
    "resourceGroupId": "rg-acfm3tmjruyribi",
    "productInfo": {
      "msgProcessSpec": "rmq.s2.2xlarge",
      "sendReceiveRatio": 0.5,
      "autoScaling": true,
      "messageRetentionTime": 72,
      "supportAutoScaling": true,
      "traceOn": true,
      "storageEncryption": false,
      "storageSecretKey": "xxxxx",
      "capacityType": "provisioned",
      "provisionedCapacity": 3000,
      "drReplicationMode": "async_cross_az"
    },
    "aclInfo": {
      "aclTypes": [
        "default"
      ],
      "defaultVpcAuthFree": true,
      "aclType": "default"
    },
    "software": {
      "softwareVersion": "5.0-rmq-20230619-1",
      "maintainTime": "02:00-06:00",
      "upgradeMethod": "auto"
    },
    "topicCount": 10,
    "groupCount": 10,
    "tags": [
      {
        "key": "key",
        "value": "value"
      }
    ]
  },
  "code": "MissingInstanceId",
  "message": "Parameter instanceId is mandatory for this action .",
  "httpStatusCode": 400,
  "dynamicCode": "InstanceId",
  "dynamicMessage": "instanceId"
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.