Query instance list
Updated at：2025-10-20
This API retrieves detailed information about all instances.
Note: Different query fields are combined with "AND," whereas multiple values for the same query field are combined with "OR."
Request structure
Plain Text
1GET /v{version}/instance?marker={marker}&maxKeys={maxKeys}&internalIp={internalIp}&dedicatedHostId={dedicatedHostId}&zoneName={zoneName}&autoRenew={autoRenew} HTTP/1.1
2Host: bcc.bj.baidubce.com
3Authorization: authorization stringRequest headers
There are no special headers required beyond the common headers.
Request parameters
| Parameter name | Types | Whether required | Parameter location | Description |
|---|---|---|---|---|
| version | String | Yes | URL parameter | API version number |
| marker | String | No | Query | The starting position of the batch list query is a system-generated string |
| maxKeys | int | No | Query | Maximum number of items included per page, maximum: 1,000, default: 1,000 |
| internalIp | String | No | Query | Internal IP address |
| dedicatedHostId | String | No | Query | Dedicated server ID |
| zoneName | String | No | Query | Availability zone information |
| instanceIds | String | No | Query | Multiple instance IDs, separated by English commas, supporting up to 100 IDs |
| volumeIds | String | No | Query | Multiple disk IDs, separated by English commas, maximum 100 IDs |
| instanceNames | String | No | Query | Enter multiple instance names separated by English commas for an exact search. Up to 100 names are supported. |
| fuzzyInstanceName | String | No | Query | Instance name supports fuzzy keyword search. You can either select instanceNames or this parameter, but not both simultaneously, as doing so will result in an error. |
| deploySetIds | String | No | Query | Multiple deployment group IDs, separated by English commas, maximum 100 |
| securityGroupIds | String | No | Query | Multiple security group IDs, separated by English commas, maximum 100 IDs |
| paymentTiming | String | No | Query | Payment method (Prepaid/Postpaid) |
| status | String | No | Query | Instance status (Recycled/Running/Stopped/Stopping/Starting) |
| tags | String | No | Query | Multiple tags, separated by commas, format: tagKey:tagValue or tagKey |
| vpcId | String | No | Query | vpcId, which can only be used in combination with the privateIps query parameter |
| privateIps | String | No | Query | Multiple intranet IPs, separated by English commas, supporting up to 100 IPs, which must be used in combination with vpcId |
| ehcClusterId | String | No | Query | EHC cluster ID |
Response headers
No special headers are required beyond the standard ones.
Response parameters
| Parameter name | Types | Description |
|---|---|---|
| marker | String | Mark the starting position of the query. |
| isTruncated | boolean | true indicates there is more data later, false indicates it is the last page |
| nextMarker | String | The marker value needed to fetch the next page. This field is absent when isTruncated is false. |
| maxKeys | int | Maximum number of items included per page |
| instances | List<[InstanceModel](BCC/API Reference/Appendix.md#InstanceModel)> | Instance information comprised of InstanceModel |
Error codes
| Error code | Error description | HTTP status code | Chinese explanation |
|---|---|---|---|
| BadRequest | zone is invalid. | 400 | Invalid availability zone |
| NoSuchObject | subnet not exists. | 404 | The subnet does not exist. |
Request example
Plain Text
1GET /v2/instance?vpcId=vpc-vv3xw6d9970b&privateIps=192.168.48.3 HTTP/1.1
2Host: bcc.bj.baidubce.com
3ContentType: application/json
4Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1deResponse example
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
3Date: Wed, 03 Dec 2014 06:42:19 GMT
4Content-Type: application/json;charset=UTF-8
5Server: BWS
6
7{
8 "marker": "",
9 "isTruncated": false,
10 "maxKeys": 1000,
11 "instances": [
12 {
13 "id": "i-zadG8d4l",
14 "name": "instance-696snyc6",
15 "roleName": "",
16 "hostname": "instance-696snyc6",
17 "instanceType": "N6",
18 "spec": "bcc.g5.c1m4",
19 "status": "Running",
20 "desc": "",
21 "createdFrom": "customPurchase",
22 "paymentTiming": "Prepaid",
23 "createTime": "2022-10-11T06:11:42Z",
24 "expireTime": "2023-01-11T06:11:42Z",
25 "internalIp": "192.168.48.3",
26 "publicIp": "",
27 "cpuCount": 1,
28 "isomerismCard": "",
29 "cardCount": "0",
30 "npuVideoMemory": "",
31 "memoryCapacityInGB": 4,
32 "localDiskSizeInGB": 0,
33 "imageId": "m-zlaNc3qH",
34 "placementPolicy": "unknown",
35 "subnetId": "sbn-2escuever5fi",
36 "vpcId": "vpc-vv3xw6d9970b",
37 "zoneName": "cn-bj-a",
38 "dedicatedHostId": "",
39 "deletionProtection": 0,
40 "deploysetList": [],
41 "autoRenew": true,
42 "ipv6": "",
43 "resGroupInfos":[
44 {
45 "groupId":"RESG-jec9gimkKaY",
46 "groupName":"test2"
47 }
48 ],
49 "nicInfo": {
50 "eniId": "eni-ramtd68yeyiq",
51 "eniUuid": "8ed449ff-b2ee-4491-b117-35fb731c4370",
52 "name": "eth0",
53 "type": "primary",
54 "subnetId": "sbn-2escuever5fi",
55 "subnetType": "BCC",
56 "az": "zoneA",
57 "description": "",
58 "deviceId": "608666b9-7156-4f47-8445-9c5497282573",
59 "status": "inuse",
60 "macAddress": "fa:f6:00:01:7e:ef",
61 "vpcId": "vpc-vv3xw6d9970b",
62 "createdTime": "Tue Oct 11 14:11:44 UTC 2022",
63 "eniNum": 1,
64 "eriNum": 0,
65 "eriInfos": [],
66 "ips": [
67 {
68 "privateIp": "192.168.48.3",
69 "eip": "null",
70 "primary": "true",
71 "eipId": "",
72 "eipAllocationId": "",
73 "eipSize": "0",
74 "eipStatus": "",
75 "eipGroupId": "",
76 "eipType": "null"
77 }
78 ],
79 "securityGroups": []
80 },
81 "eniNum": "1",
82 "tags": [
83 {
84 "tagKey": "test2",
85 "tagValue": "bcc"
86 }
87 ],
88 "networkCapacityInMbps": 0
89 }
90 ]
91}