查询指定业务下已创建的云手机实例的详细信息。支持单个实例查询、多个实例查询、全量实例查询，以及基于特定字段的筛选实例查询。

使用说明

如需查询指定实例的详细信息，请通过 PodIdList 参数传入目标实例 ID；不指定任何实例 ID 时默认查询所有符合筛选条件（如有）的实例详情。

注意事项

本接口的单用户 QPS 限制为 30 次/秒。超过限制，API 调用会被限流。

请求说明

请求方式：POST

请求地址：https://open.volcengineapi.com?Action=ListPod&Version=2025-05-01

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	ListPod	接口名称。当前 API 的名称为 ListPod。
Version	String	是	2025-05-01	接口版本。当前 API 的版本为 2025-05-01。

Body

参数	类型	是否必选	示例值	描述
ProductId	String	是	1635714550******	业务 ID，用于指定想要查询的目标业务。可登录云手机控制台，在已创建的业务卡片中获取。
PodIdList	Array of String	否	["7294157141458****", "7294107154305****"]	实例 ID 列表。如需查询指定实例的详细信息，请通过本参数设置目标实例 ID 列表。最多支持传入 100 个 ID。
ConfigurationCodeList	Array of String	否	["ultimate", "enhanced"]	云手机实例套餐规格 ID。使用本参数可以筛选出指定规格的云手机实例进行查询。当前业务下已购入的实例可选规格可以通过 ListPodResource 接口查询。
RegionList	Array of String	否	["cn-north", "cn-south"]	实例归属机房所在的大区 ID。使用本参数可以筛选出指定大区的云手机实例进行查询。包含以下取值： cn-north：华北 cn-south：华南 cn-east：华东 cn-middle：华中 cn-southwest：西南 cn-northwest：西北
DcList	Array of String	否	["gdsz-ctcucm-01-1", "gdsz-ctcucm-01-2"]	实例归属机房 ID。使用本参数可以筛选出指定机房的云手机实例进行查询。
TagIdList	Array of String	否	["01", "02"]	标签 ID。使用本参数可以筛选出添加了指定标签的云手机实例进行查询。当前业务下已创建的标签可通过调用 ListTag 接口获取。
OnlineList	Array of Integer	否	[1, 2]	实例运行状态。使用本参数可以筛选出指定运行状态的云手机实例进行查询。包含以下取值： 0：开机中 1：运行中 2：已关机 3：关机中 4：重启中
StreamStatusList	Array of Integer	否	[1, 2]	实例推流状态。使用本参数可以筛选出指定推流状态的云手机实例进行查询。包含以下取值： 0：空闲 1：推流中 2：就绪更多相关说明参看实例推流状态说明。
AuthorityStatus	Integer	否	1	实例运维授权状态。使用本参数可以筛选出指定运维状态的云手机实例进行查询。包含以下取值： 1：未授权 2：已授权
ZoneId	String	否	gdsz-ctcucm-01	实例归属机房所在片区 ID。使用本参数可以筛选出指定片区的云手机实例进行查询。可通过 ListDc 接口返回的 Zone字段获取。
ServerTypeCode	String	否	g2.8c12g	云机规格。本地存储业务可以使用本参数筛选指定规格云机上的云手机实例进行查询。云机规格详情参看本地存储云机规格列表。
HostId	String	否	7235890389201******	云机 ID。本地存储业务可以使用本参数筛选出指定云机上的云手机实例进行查询。可通过 ListHost 接口获取。
DNSId	String	否	dns-7417778232776******	DNS 规则 ID。关联了自定义 DNS 规则的实例，可使用本参数筛选出指定规则查询关联实例详情。
PodName	String	否	pod_name	实例名称，可以根据实例名称精确查找。
ArchiveStatus	Integer	否	2	实例备份/还原状态。本地存储业务若已调用 BackupPod 或 RestorePod 接口对实例执行备份还原操作，使用本参数可以筛选出对应状态的云手机实例进行查询。取值如下： -2：还原失败 -1：备份失败 0：正常状态 1：备份中 2：备份完成 3：还原中 5：备份排队中 6：还原排队中 7：备份取消中 8：还原取消中
MaxResults	Integer	否	10	分页查询时用于设置每页返回的条目数。最大值为 100，默认值为 10。
NextToken	String	否	wyc87CUcfU1pIlpAinyljWVCLc0mqRLetP99DZs-v3yv4x5DRq9FGdWtT**********xlc8mJ1VRIATB_Dv1Tcn0YJdiq1k9XzjGDLArAgX6g3CzaFNGy7gUqkOb2U-k	分页查询凭证，用于标记查询数据的起始位置。初次查询时无需设置，服务器将根据筛选条件返回一部分数据，并返回一个 NextToken 凭证值记录这批数据的结尾位置，作为下次查询的起始位置。后续查询中，将上一次查询时返回的 NextToken 作为参数传入，服务器会从该位置继续返回后续数据。 Warning 重复调用本接口进行接续查询时，不可修改原始筛选条件，否则会影响查询数据的连贯性和准确性。如需修改筛选条件，请将本参数置空，从第一条数据开始重新查询。接口返回的 NextToken 有效期为 2 小时，若传入过期或无效的值，服务器将从第一条数据开始重新查询并返回。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
Row	Array of Pod	-	查询到的实例详细信息。
NextToken	String	wyc87CUcfU1pIlpAinyljWVCLc0mqRLetP99DZs-v3yv4x5DRq9FGdWtT**********xlc8mJ1VRIATB_Dv1Tcn0YJdiq1k9XzjGDLArAgX6g3CzaFNGy7gUqkOb2U-k	本次调用返回的查询凭证，若返回空置即表示该页为末页。 Warning NextToken 有效期为 2 小时，若下次请求时使用了过期凭证，则将从第一条数据开始重新查询。

Pod

参数	类型	示例值	描述
ProductId	String	1635714550******	实例归属业务 ID。
PodId	String	7294157141458******	实例 ID。
PodName	String	pod_name	实例名称。
ImageId	String	img-1146****	实例使用的镜像 ID。
ImageName	String	平台公共镜像AOSP11(06-20)	实例使用的镜像名称。
Tag	Object of PodTag	-	实例绑定的标签信息。
DcInfo	Object of PodDc	-	实例归属的机房信息。
Configuration	Object of Configuration	-	实例套餐规格信息。
DataSize	String	4Gi	实例设置的预占存储容量。
DataSizeUsed	String	0.582Gi	实例实际占用的存储容量。
DisplayLayoutId	String	single-display-landscape	屏幕布局 ID。系统屏幕布局包含以下取值： single-display-landscape：1080p 横屏，分辨率 19201080 像素，像素密度 320 dpi，帧率 60fps； single-display-portrait：1080p 竖屏，分辨率 10801920 像素，像素密度 320 dpi，帧率 60fps； single-display-portrait-720p：高清竖屏，分辨率 720*1080 像素，像素密度 320 dpi，帧率 30fps。
Adb	String	123.0.0.1:1234	ADB 地址，返回空值表示未开启 ADB。
AdbStatus	Integer	0	ADB 开关状态。包含以下取值： 0：关闭 1：开启
AdbExpireTime	Long	0	ADB 过期时间。小于或等于 0 表示无过期时间。
Online	Integer	1	实例运行状态。包含以下取值： 0：开机中 1：运行中 2：已关机 3：关机中 4：重启中
IntranetIP	String	10.xx.xxx.xx	实例的内网 IP。
StreamStatus	Integer	1	实例推流状态。包含以下取值： 0：空闲 1：推流中 2：就绪
UpBandwidthLimit	Integer	0	实例上行带宽上限，单位为 Mbps。0 表示未设置限速。
DownBandwidthLimit	Integer	0	实例下行带宽上限，单位为 Mbps。0 表示未设置限速。
AospVersion	String	10	实例镜像版本。包含以下取值： 10：AOSP 10 11：AOSP 11 13：AOSP 13
CreateAt	Long	1692000000	实例创建时间，Unix 时间戳。
AuthorityStatus	Integer	1	实例授权运维状态。包含以下取值： 1：未授权 2：已授权
AuthorityExpireTime	Long	0	实例授权运维过期时间。小于或等于 0 表示无过期时间。
PortMappingRuleList	Array of PortMappingRule	-	端口映射列表。
HostId	String	host-7337959478131******	实例归属云机 ID。
ServerTypeCode	String	g2.8c12g	实例归属云机的规格。
DNSId	String	dns-7417778232776******	实例关联的自定义 DNS 规则 ID。
Eip	Object of PodEip	-	EIP（弹性公网 IP）的相关信息。注意仅部分机房返回此参数。
ArchiveStatus	Integer	2	实例的备份还原状态。取值如下： -2：还原失败 -1：备份失败 0：正常状态 1：备份中 2：备份完成 3：还原中 5：备份排队中 6：还原排队中 7：备份取消中 8：还原取消中
CustomRouteId	String	cr-1234****	自定义路由 ID。

PodTag

参数	类型	示例值	描述
TagId	String	tag01	标签 ID。
TagDesc	String	tag01	标签描述。
TagName	String	标签01	标签名称。

PodDc

参数	类型	示例值	描述
Dc	String	gdsz-ctcucm-01-1	机房 ID。
DcName	String	广东深圳三线01-1	机房名称。
Isp	Integer	7	运营商。包含以下取值： 1：中国移动 2：中国联通 4：中国电信 7：移动&联通&电信（三线） 8：BGP
Region	String	cn-south	机房所在大区。包含以下取值： cn-north：中国大陆华北 cn-south：中国大陆华南 cn-east：中国大陆华东 cn-middle：中国大陆华中 cn-southwest：中国大陆西南 cn-northwest：中国大陆西北 cn-hongkong-pop：中国香港
ZoneId	String	gdsz-ctcucm-01	机房所在区域 ID。

Configuration

参数	类型	示例值	描述
ConfigurationCode	String	basic	云手机实例规格 ID。
ConfigurationName	String	基础型	与 ConfigurationCode 相对应的实例规格名称。
ConfigurationType	Integer	1	云手机实例规格类型。包含以下取值： 1：正式 2：试用
ServerTypeCode	String	g2.8c12g	云机规格，详情参看本地存储云机规格列表。

PortMappingRule

参数	类型	示例值	描述
Status	Integer	256	端口映射状态。包含以下取值： 256：打开中 257：打开完成 512：关闭中 513：关闭完成 768：销毁中 769：销毁完成
Protocol	String	tcp	端口映射策略。包含以下取值： tcp udp
PublicIp	String	111.xx.xxx.xx	端口映射对应公网 IP。
PublicPort	Integer	6567	端口映射对应公网端口。
SourcePort	Integer	5555	端口映射源端口。
PortMappingRuleId	String	rule01	对应端口映射规则 ID。
PublicPortInfoList	Array of PublicPortInfo	-	公共端口信息列表。

PodEip

参数	类型	示例值	描述
Isp	Integer	4	运营商信息，包含如下取值： 1：中国移动 2：中国联通 4：中国电信 8：静态BGP
EipId	String	eip-21103821xxx	EIP ID。
EipAddress	String	180.xxx.xxx.xx	EIP 地址。

PublicPortInfo

参数	类型	示例值	描述
Isp	Integer	1	运营商。取值如下： 1：中国移动 2：中国联通 4：中国电信
PublicIp	String	111.xx.xxx.xx	公共 IP。
PublicPort	Integer	1094	公共端口。

请求示例

返回示例

错误码

您可访问公共错误码，获取更多错误码信息。