All Products
Search

This Product

    ApsaraMQ for RocketMQ:GetInstance

    Document Center

    ApsaraMQ for RocketMQ:GetInstance

    Last Updated:Dec 19, 2025

    Retrieves the details of a specified instance.

    Operation description

    Important The OpenAPI provided by Alibaba Cloud is a management application programming interface (API). You can use it to manage and query Alibaba Cloud service resources. This API is for management purposes only. Do not use this API on the core data path for sending or receiving messages because this can create risks for your data link.

    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.

    requestId

    string

    The ID of the request. Each request has a unique ID. Use this ID to troubleshoot issues.

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

    boolean

    Indicates whether the request was successful.

    true
    data

    object

    The returned result.

    regionId

    string

    The ID of the region where the instance is located.

    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 is released.

    • RUNNING: The instance is running.

    • STOPPED: The instance is stopped.

    • CHANGING: The instance is being changed.

    • 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 ID of the user to whom the instance belongs.

    111111111111111
    bid

    string

    The BID of the sales channel.

    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 service code for ApsaraMQ for RocketMQ is rmq.

    rmq
    seriesCode

    string

    The primary series code of the instance. For more information about the differences between primary series, 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 sub-series, 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 remarks on the instance.

    This is remark for instance.
    networkInfo

    object

    The network information.

    vpcInfo

    object

    The Virtual Private Cloud (VPC) information.

    vpcId

    string

    The ID of the VPC associated with the instance.

    vpc-uf6of9452b2pba82c****
    vSwitchId deprecated

    string

    The ID of the vSwitch associated with the instance.

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

    vsw-uf6gwtbn6etadpvz7****
    vSwitches

    array<object>

    The list of vSwitches.

    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>

    The endpoint information.

    object

    The endpoint information.

    endpointType

    string

    The type of the instance endpoint.

    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 you do not configure an IP address whitelist, all IP addresses can access the ApsaraMQ for RocketMQ server over the public network by default.

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

    This field is deprecated. Use the internetInfo.ipWhitelist field instead.

    192.168.x.x/24

    string

    The IP address whitelist for public network access.

    192.168.x.x/24
    endpointId

    string

    ep-bpxxx
    internetInfo

    object

    The public network information of the instance.

    internetSpec

    string

    Indicates whether to enable public network access.

    Valid values:

    • enable: Public network access is enabled.

    • disable: Public network access is disabled.

    Instances support VPC access by default. If you enable public network access, ApsaraMQ for RocketMQ charges for downstream public bandwidth. For more information about billing, see Public network access fees.

    Valid values:

    • enable :

      Enabled

    • disable :

      Disabled

    enable
    flowOutType

    string

    The billing method for public network usage.

    Valid values:

    • payByBandwidth: pay-by-bandwidth. This value applies when public network access is enabled.

    • uninvolved: not applicable. This value applies when public network access is disabled.

    Valid values:

    • payByBandwidth :

      pay-by-bandwidth

    • uninvolved :

      not applicable

    payByBandwidth
    flowOutBandwidth

    integer

    The public bandwidth specification. Unit: Mbps.

    1
    ipWhitelist

    array

    The list of IP addresses in the public access whitelist.

    • If you do not configure an IP address whitelist, all IP addresses can access the ApsaraMQ for RocketMQ server over the public network by default.

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

    string

    The IP address whitelist for public network access.

    192.168.x.x/24
    accountInfo

    object

    The account information.

    username

    string

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

    6W0xz2uPfiwp****
    instanceQuotas

    array<object>

    The capacity information.

    object

    The capacity information.

    quotaName

    string

    The name of the instance quota.

    Valid values:

    • TOPIC_COUNT: The topic quota of the instance.

    Valid values:

    • TOPIC_COUNT :

      The topic quota of the instance.

    TOPIC_COUNT
    usedCount

    number

    The used amount.

    10
    freeCount

    number

    The free quota.

    20
    totalCount

    number

    The total 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 modified.

    2022-08-02 00:00:00

    extConfig deprecated

    object

    Extended configuration. This field is deprecated. Use fields such as productInfo, internetInfo, and aclInfo instead.

    aclType

    string

    The authentication type of the instance.

    Valid values:

    • 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

    Indicates whether to enable elastic scaling beyond specifications.

    Valid values:

    • true: Enabled

    • false: Disabled

    This parameter is valid only when the supportAutoScaling parameter is set to enable, which means the instance supports elastic scaling.

    Valid values:

    • true :

      Enabled

    • false :

      Disabled

    true
    messageRetentionTime

    integer

    The message retention period. Unit: hours.

    For the value range, see the limits on the message retention period in Limits>Resource Quotas.

    Message storage in ApsaraMQ for RocketMQ is fully serverless and elastic. You are charged for the actual storage space that you use. You can control the storage capacity by adjusting the message retention period. For more information, see Storage fees.

    72
    supportAutoScaling

    boolean

    Indicates whether the instance supports elastic scaling beyond specifications.

    Valid values:

    • true: Supported

    • false: Not supported

    After you enable elastic scaling, ApsaraMQ for RocketMQ lets the instance exceed the Transaction Per Second (TPS) limit of the basic specifications within a certain range. You are charged an extra fee for the elastic specifications that exceed the basic specifications. For more information about billing, see Computing capacity fees.

    Note

    Only instances of specific specifications support elastic scaling. For information about the supported instances, see Instance types.

    Valid values:

    • true :

      Supported

    • false :

      Not supported

    true
    internetSpec

    string

    Indicates whether to enable public network access.

    Valid values:

    • enable: Enabled

    • disable: Disabled

    Instances support VPC access by default. If you enable public network access, ApsaraMQ for RocketMQ charges for downstream public bandwidth. For more information about billing, see Public network access fees.

    Valid values:

    • enable :

      Enabled

    • disable :

      Disabled

    enable
    flowOutType

    string

    The billing method for public network usage.

    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 specification. Unit: Mbps.

    10
    msgProcessSpec

    string

    The computing specification for sending and receiving messages. For the upper limit of TPS for sending and receiving messages, see Instance types.

    rmq.s2.2xlarge
    resourceGroupId

    string

    The ID of the resource group.

    rg-acfm3tmjruyribi
    productInfo

    object

    The extended configuration of the instance.

    msgProcessSpec

    string

    The computing specification for sending and receiving messages. For the upper limit of TPS for sending and receiving messages, see Instance types.

    rmq.s2.2xlarge
    sendReceiveRatio

    number

    The ratio of sent messages to received messages.

    0.5
    autoScaling

    boolean

    Indicates whether to enable elastic scaling beyond specifications.

    Valid values:

    • true: Enabled

    • false: Disabled

    This parameter is valid only when the supportAutoScaling parameter is set to enable, which means the instance supports elastic scaling.

    Valid values:

    • true :

      Enabled

    • false :

      Disabled

    true
    messageRetentionTime

    integer

    The message retention period. Unit: hours.

    For the value range, see the limits on the message retention period in Limits>Resource Quotas.

    Message storage in ApsaraMQ for RocketMQ is fully serverless and elastic. You are charged for the actual storage space that you use. You can control the storage capacity by adjusting the message retention period. For more information, see Storage fees.

    72
    supportAutoScaling

    boolean

    Indicates whether the instance supports elastic scaling beyond specifications.

    Valid values:

    • true: Supported

    • false: Not supported

    After you enable elastic scaling, ApsaraMQ for RocketMQ lets the instance exceed the TPS limit of the basic specifications within a certain range. You are charged an extra fee for the elastic specifications that exceed the basic specifications. For more information about billing, see Computing capacity fees.

    Note

    Only instances of specific specifications support elastic scaling. For information about the supported instances, see Instance types.

    Valid values:

    • true :

      Supported

    • false :

      Not supported

    true
    traceOn

    boolean

    Indicates whether the message trace feature is enabled.

    • true: Enabled

    • false: Disabled

    This parameter is not yet effective. The message trace feature is supported by default, regardless of whether this parameter is enabled.

    true
    storageEncryption

    boolean

    Indicates whether storage encryption is enabled.

    false
    storageSecretKey

    string

    The key for storage encryption.

    xxxxx
    capacityType

    string

    The capacity mode:

    • provisioned: provisioned + elastic

    • ondemand: on-demand

    Valid values:

    • provisioned :

      provisioned + elastic

    • ondemand :

      on-demand

    provisioned
    provisionedCapacity

    integer

    The provisioned capacity.

    3000
    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

    The switch for authentication-free access over the internal network.

    Valid values:

    • true :

      Enabled

    • false :

      Disabled

    true
    aclType deprecated

    string

    The authentication type of the instance. This field is deprecated. Use the aclTypes field 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 upgrade time 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
    },
    "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.