接口请求域名： edgezone.intl.tencentcloudapi.com 。
查询物理机实例列表，支持按实例ID、实例名称、可用区、实例状态等条件筛选，并支持分页查询。
默认接口请求频率限制：20次/秒。
以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
| 参数名称 | 必选 | 类型 | 描述 |
|---|---|---|---|
| Action | 是 | String | 公共参数，本接口取值：DescribeInstances。 |
| Version | 是 | String | 公共参数，本接口取值：2026-04-01。 |
| Region | 是 | String | 公共参数，详见产品支持的 地域列表。 |
| InstanceIds.N | 否 | Array of String | 实例ID列表，用于按实例ID筛选 |
| InstanceName | 否 | String | 实例名称，支持模糊匹配 |
| Zone | 否 | String | 可用区代码，用于筛选指定可用区的实例 |
| InstanceStatus.N | 否 | Array of String | 实例状态列表，用于按状态筛选实例。可选值：allocating、running、isolating、isolated、terminating、error |
| PublicIps.N | 否 | Array of String | 公网IPv4地址列表，用于按公网IP筛选实例 |
| Offset | 否 | Integer | 偏移量，默认0 |
| Limit | 否 | Integer | 返回数量，默认20，最大100 |
| 参数名称 | 类型 | 描述 |
|---|---|---|
| InstanceSet | Array of Instance | 实例详细信息列表 |
| TotalCount | Integer | 符合条件的实例数量 |
| RequestId | String | 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。 |
查询广州一区运行中的实例列表
POST / HTTP/1.1
Host: edgezone.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeInstances
<公共请求参数>
{
"Zone": "ap-guangzhou-1",
"InstanceStatus": [
"running"
],
"Offset": 0,
"Limit": 20
}
{
"Response": {
"InstanceSet": [
{
"InstanceId": "bms-efgh5678",
"InstanceName": "web-server-01",
"MachineId": "srv-efgh5678",
"InstanceType": "BM.S5.LARGE8",
"Zone": "ap-guangzhou-1",
"ImageId": "img-ubuntu-20.04",
"VersionNumber": "20.04",
"InstanceStatus": "running",
"OperateStatus": "normal",
"PrivateNetworkId": "net-private-002",
"PrivateIp": "10.0.0.2",
"PrivateIpV6": "",
"PublicNetworkId": "net-public-002",
"PublicIp": "203.0.113.20",
"PublicIpV6": "",
"CreatedTime": "2026-02-15T14:30:00Z"
}
],
"TotalCount": 1,
"RequestId": "b5d7f3a2-c418-4b9e-9c72-4a1e6d3f8b90"
}
}
按实例ID查询实例列表
POST / HTTP/1.1
Host: edgezone.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeInstances
<公共请求参数>
{
"InstanceIds": [
"bms-abcd1234"
],
"Offset": 0,
"Limit": 20
}
{
"Response": {
"InstanceSet": [
{
"InstanceId": "bms-abcd1234",
"InstanceName": "my-epm-instance",
"MachineId": "srv-abcd1234",
"InstanceType": "BM.S5.LARGE8",
"Zone": "ap-guangzhou-1",
"ImageId": "img-centos-7.9",
"VersionNumber": "7.9.2009",
"InstanceStatus": "running",
"OperateStatus": "normal",
"PrivateNetworkId": "net-private-001",
"PrivateIp": "10.0.0.1",
"PrivateIpV6": "fd00::1",
"PublicNetworkId": "net-public-001",
"PublicIp": "203.0.113.10",
"PublicIpV6": "2001:db8::1",
"CreatedTime": "2026-01-13T10:00:00Z"
}
],
"TotalCount": 1,
"RequestId": "eac6b301-a322-493a-8e36-83b295459397"
}
}
云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。
该接口暂无业务逻辑相关的错误码，其他错误码详见 公共错误码。
文档反馈