tencent cloud

APIs

文档APIsTencent Cloud Distributed Cache (Redis OSS-Compatible)Instance APIsDescribeInstances

DescribeInstances

下载
聚焦模式
字号
最后更新时间： 2026-11-09 15:07:02

1. API Description

Domain name for API request: redis.intl.tencentcloudapi.com.

This API is used to query the list of Redis instances.

A maximum of 35 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: DescribeInstances.
Version Yes String Common Params. The value used for this API: 2018-04-12.
Region Yes String Common Params. For more information, please see the list of regions supported by the product.
Limit No Integer

Number of instances output per page. Default parameter value: 20. Maximum value: 1000.
Offset No Integer

Pagination offset, which is an integer multiple of Limit. Calculation formula: offset=limit*(page number-1).
InstanceId No String

Specifies the instance ID. Example: crs-xjhsdj****. Log in to the Redis console and copy the instance ID from the instance list.
OrderBy No String

Instance list sorting criteria. Enumeration values are as follows:

  • projectId: by project ID.
  • createtime: sort by instance creation time.
  • instancename: by instance name sorting.
  • type: by instance type.
  • curDeadline: by instance expiration time.
OrderType No Integer

Instance sorting order, with a default value of reverse sorting.

  • 1: Reverse order.
  • 0: Sequential order.
VpcIds.N No Array of String

VPC ID array. If this parameter is not configured or the array is empty, the basic network is selected by default. For example: 47525. This parameter is temporarily reserved and can be ignored. Set the VPC ID array according to the format of the UniqVpcIds parameter.
SubnetIds.N No Array of String

Array of subnet IDs belonging to the private network, for example: 56854. This parameter is temporarily reserved and can be ignored. Set the private network subnet ID array according to the format of the UniqSubnetIds parameter.
SearchKey No String

Set the key field for fuzzy query. Only instance names support fuzzy query.
ProjectIds.N No Array of Integer

Array of project IDs.
InstanceName No String

Instance name.
UniqVpcIds.N No Array of String

VPC ID array. If this parameter is not configured or the array is empty, the basic network is selected by default, for example: vpc-sad23jfdfk.
UniqSubnetIds.N No Array of String

Subnet ID array belonging to the private network, for example: subnet-fdj24n34j2.
RegionIds.N No Array of Integer

Region ID array. This parameter has been deprecated. Use the common parameter Region to query the corresponding region.
Status.N No Array of Integer

Instance status.

  • 0: pending initialization.
  • 1: in process.
  • 2: running.
  • -2: isolated.
  • -3: pending deletion.
TypeVersion No Integer

Instance architecture version.

  • 1: standalone edition.
  • 2: primary/secondary edition.
  • 3: cluster version.
EngineName No String

Storage engine info. It can be set to Redis-2.8, Redis-4.0, Redis-5.0, Redis-6.0, or CKV.
AutoRenew.N No Array of Integer

Renewal mode.

  • 0: Manual renewal.
  • 1: Automatic renewal.
  • 2: No renewal after expiry.
BillingMode No String

Billing mode.

  • postpaid: pay-as-you-go billing.
  • prepaid: annual/monthly subscription.
Type No Integer

Instance type.

  • 2: Redis 2.8 memory edition (standard architecture).
  • 3: CKV 3.2 memory edition (standard architecture).
  • 4: CKV 3.2 memory edition (cluster architecture).
  • 5: Redis 2.8 memory edition (standalone).
  • 6: Redis 4.0 memory edition (standard architecture).
  • 7: Redis 4.0 memory edition (cluster architecture).
  • 8: Redis 5.0 memory edition (standard architecture).
  • 9: Redis 5.0 memory edition (cluster architecture).
  • 15: Redis 6.2 memory edition (standard architecture).
  • 16: Redis 6.2 memory edition (cluster architecture).
  • 17: Redis 7.0 memory edition (standard architecture).
  • 18: Redis 7.0 memory edition (cluster architecture).
  • 200: Memcached 1.6 memory edition (cluster architecture).
SearchKeys.N No Array of String

This parameter is an array type and supports configuring instance name, instance ID, and IP address. Among them, instance name uses fuzzy matching, while instance ID and IP address use exact matching.

  • Each element in the array uses union for match query.
  • If InstanceId and SearchKeys are configured concurrently, their intersection is used for matching query.
TypeList.N No Array of Integer

Internal parameter, which can be ignored.
MonitorVersion No String

Internal parameter, which can be ignored.
InstanceTags.N No Array of InstanceTagInfo

Filter resources by tag Key and Value. If this parameter is not configured or the array is set to empty, no tag-based filtering is applied.
TagKeys.N No Array of String

Filter resources by tag Key. If this parameter is not configured or the array is set to empty, no filtering by tag Key is performed.
ProductVersions.N No Array of String

Deployment type of the instance. If this parameter is not configured or the array is set to empty, instances will not be filtered based on this parameter by default.

Enumeration values:

  • local: Common I.
  • localv2: Common II.
  • cdc: Dedicated cluster.
InstanceIds.N No Array of String

Batch query the specified instance IDs. The returned results are mainly limited by Limit.
AzMode No String

Availability zone mode.

  • singleaz: single availability zone.
  • multiaz: multi-availability zone.

3. Output Parameters

Parameter Name Type Description
TotalCount Integer

Total number of instances.
InstanceSet Array of InstanceSet

Instance detail list.
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Request Example

This example shows you how to query the list of Redis instances.

Input Example

POST / HTTP/1.1
Host: redis.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeInstances
<Common request parameters>

{
    "Limit": 2,
    "Offset": 0,
    "OrderBy": "createtime "
}

Output Example

{
    "Response": {
        "InstanceSet": [
            {
                "Appid": 251223628,
                "AutoRenewFlag": 0,
                "BillingMode": 1,
                "ClientLimit": 10000,
                "ClientLimitMax": 40000,
                "ClientLimitMin": 10000,
                "CloseTime": "0000-00-00 00:00:00",
                "Createtime": "2023-04-17 11:32:18",
                "CurrentProxyVersion": "5.8.0",
                "CurrentRedisVersion": "6.0.0",
                "DeadlineTime": "2023-05-17 11:32:18",
                "DedicatedClusterId": "",
                "DiskSize": 0,
                "DtsStatus": 0,
                "Engine": "Redis",
                "InstanceId": "crs-4nmzc0ul",
                "InstanceName": "Redis_automation_is_awesome",
                "InstanceNode": [],
                "InstanceTags": [],
                "InstanceTitle": "Adding an Instance",
                "MonitorVersion": "5s",
                "NetLimit": 24,
                "NoAuth": false,
                "NodeSet": [
                    {
                        "NodeId": 336948,
                        "NodeType": 0,
                        "ZoneId": 100002,
                        "ZoneName": ""
                    },
                    {
                        "NodeId": 336946,
                        "NodeType": 1,
                        "ZoneId": 100003,
                        "ZoneName": ""
                    },
                    {
                        "NodeId": 336947,
                        "NodeType": 1,
                        "ZoneId": 100004,
                        "ZoneName": ""
                    }
                ],
                "OfflineTime": "",
                "PasswordFree": 0,
                "PolarisServer": "",
                "Port": 6379,
                "PriceId": 1000848,
                "ProductType": "standalone",
                "ProductVersion": "local",
                "ProjectId": 0,
                "ProjectName": "Default Project",
                "ReadOnly": 0,
                "RedisClusterId": "",
                "RedisReplicasNum": 2,
                "RedisShardNum": 1,
                "RedisShardSize": 4096,
                "Region": "ap-guangzhou",
                "RegionId": 1,
                "RemainBandwidthDuration": "",
                "Size": 4096,
                "SlaveReadWeight": 0,
                "Status": 1,
                "SubStatus": 37,
                "SubnetId": 2282634,
                "Tags": [],
                "Type": 15,
                "UniqSubnetId": "subnet-1ed4w7to",
                "UniqVpcId": "vpc-mjwornzj",
                "UpgradeProxyVersion": "",
                "UpgradeRedisVersion": "",
                "Vip6": "",
                "VpcId": 11133673,
                "WanAddress": "",
                "WanIp": "10.0.1.61",
                "ZoneId": 100002
            },
            {
                "Appid": 251223628,
                "AutoRenewFlag": 0,
                "BillingMode": 1,
                "ClientLimit": 10000,
                "ClientLimitMax": 40000,
                "ClientLimitMin": 10000,
                "CloseTime": "0000-00-00 00:00:00",
                "Createtime": "2023-04-17 11:47:02",
                "CurrentProxyVersion": "5.5.0",
                "CurrentRedisVersion": "92.0.0",
                "DeadlineTime": "2023-05-17 11:47:01",
                "DedicatedClusterId": "",
                "DiskSize": 0,
                "DtsStatus": 0,
                "Engine": "Redis",
                "InstanceId": "crs-46njvft9",
                "InstanceName": "Redis_automation_is_awesome",
                "InstanceNode": [],
                "InstanceTags": [],
                "InstanceTitle": "Running",
                "MonitorVersion": "5s",
                "NetLimit": 24,
                "NoAuth": false,
                "NodeSet": [
                    {
                        "NodeId": 336951,
                        "NodeType": 0,
                        "ZoneId": 100002,
                        "ZoneName": ""
                    },
                    {
                        "NodeId": 336949,
                        "NodeType": 1,
                        "ZoneId": 100003,
                        "ZoneName": ""
                    },
                    {
                        "NodeId": 336950,
                        "NodeType": 1,
                        "ZoneId": 100004,
                        "ZoneName": ""
                    }
                ],
                "OfflineTime": "",
                "PasswordFree": 0,
                "PolarisServer": "",
                "Port": 6379,
                "PriceId": 1000848,
                "ProductType": "standalone",
                "ProductVersion": "local",
                "ProjectId": 0,
                "ProjectName": "Default Project",
                "ReadOnly": 0,
                "RedisClusterId": "",
                "RedisReplicasNum": 2,
                "RedisShardNum": 1,
                "RedisShardSize": 4096,
                "Region": "ap-guangzhou",
                "RegionId": 1,
                "RemainBandwidthDuration": "",
                "Size": 4096,
                "SizeUsed": 0,
                "SlaveReadWeight": 0,
                "Status": 2,
                "SubStatus": 19,
                "SubnetId": 2282634,
                "Tags": [],
                "Type": 6,
                "UniqSubnetId": "subnet-1ed4w7to",
                "UniqVpcId": "vpc-mjwornzj",
                "UpgradeProxyVersion": "",
                "UpgradeRedisVersion": "",
                "Vip6": "",
                "VpcId": 11133673,
                "WanAddress": "",
                "WanIp": "10.0.1.71",
                "ZoneId": 100002
            }
        ],
        "RequestId": "3fb5a4d2-680c-45a2-aa88-0213b76d1489",
        "TotalCount": 8
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation.SystemError Internal system error, which is irrelevant to the business.
FailedOperation.Unknown Invalid data is entered for weekday.
InternalError.DbOperationFailed Internal system error with the database operation, which may be update, insert, select, etc.
InvalidParameter Incorrect parameter.
InvalidParameter.EmptyParam The parameter is empty.
InvalidParameter.InvalidParameter Invalid service parameter.
InvalidParameter.PermissionDenied The API has no CAM permissions.
UnauthorizedOperation.NoCAMAuthed No CAM permissions.
UnsupportedOperation The operation is not supported.
上一篇: DescribeInstanceZoneInfo下一篇: DescribeProxySlowLog

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档