Querying Virtual Subnets

Function

This API is used to query information about all subnets, including the subnet name and ID.

Calling Method

For details, see Calling APIs.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

vpc:subnets:list

List

subnet *

-

vpc:subnets:get

-

-

g:EnterpriseProjectId

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
vpc:subnets:list	List	subnet *	-	vpc:subnets:get	-
-	g:EnterpriseProjectId

URI

GET /v3/{project_id}/vpc/virsubnets

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: ID of the project that the subnet belongs to. For details about how to obtain a project ID, see Obtaining a Project ID. Range: N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
limit	No	Integer	Definition: Number of resources on each page. Range: 0 to 2000
marker	No	String	Definition: Start resource ID of pagination query. If the parameter is left blank, only resources on the first page are queried. Range: Subnet ID.
id	No	Array of strings	Definition: ID of the subnet, which can be used to filter the subnet. Multiple IDs can be specified for filtering. Range: N/A
name	No	Array of strings	Definition: Subnet name, which can be used to filter the subnet. Multiple names can be specified for filtering. Range: N/A
vpc_id	No	Array of strings	Definition: ID of the VPC that the subnet belongs to, which can be used to filter the subnet. Multiple IDs can be specified for filtering. Range: N/A
status	No	String	Definition: Subnet status, which can be used to filter the subnet. Only one status can be specified for filtering. Range: ACTIVE: The subnet has been associated with a VPC. UNKNOWN: The subnet has not been associated with a VPC. ERROR: The subnet is abnormal.
scope	No	Array of strings	Definition: Scope of the subnet. If this parameter is specified, the subnet can be filtered by scope. Multiple scopes can be specified for filtering. Range: center: The subnet is in a central AZ. {publicBorderGroup}: The subnet is in a public border group. The public border group limits the AZs of a subnet but it can have multiple edge AZs associated.
zone_id	No	Array of strings	Definition: AZ ID of the subnet. If this parameter is specified, the subnet can be filtered by AZ ID. Multiple AZ IDs can be specified for filtering. Range: N/A
description	No	Array of strings	Definition: Description of the subnet, which can be used to filter the subnet. Multiple descriptions can be specified for filtering. Range: N/A

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
request_id	String	Definition: Request ID. Range: N/A.
virsubnets	Array of Virsubnet objects	Definition: Response body for querying the subnets. Range: N/A.
page_info	PageInfo object	Definition: Pagination information. Range: N/A.

**Table 4** Virsubnet
Parameter	Type	Description
id	String	Definition: Subnet ID. After a subnet is created, a subnet ID is generated, which uniquely identifies the subnet. Range: The value is in UUID format with hyphens (-).
name	String	Definition: Subnet name. Range: The value can contain 1 to 64 characters, including letters, digits, underscores (_), hyphens (-), and periods (.).
description	String	Definition: Supplementary information about a subnet. Range: The value can contain 0 to 255 characters and cannot contain angle brackets (< or >).
dns_nameservers	Array of strings	Definition: DNS server addresses of a subnet. Range: N/A.
zone_id	String	Definition: ID of the AZ that the subnet belongs to. Range: N/A
vpc_id	String	Definition: ID of the VPC that the subnet belongs to. Range: N/A
status	String	Definition: Subnet status. Range: ACTIVE: The subnet has been associated with a VPC. UNKNOWN: The subnet has not been associated with a VPC. ERROR: The subnet is abnormal.
project_id	String	Definition: ID of the project that the subnet belongs to. Range: N/A
scope	String	Definition: Scope of the subnet (edge cloud scenario). Range: center: The subnet is in a central AZ. {publicBorderGroup}: The subnet is in a public border group. The public border group limits the AZs of a subnet but it can have multiple edge AZs associated.
subnet_cidrs	Array of SubnetCidr objects	Definition: OpenStack Neutron subnet information. Range: N/A
tags	Array of ResponseTag objects	Definition: Tags of a subnet, including tag keys and tag values, which can be used to classify and identify resources. For details, see the tag objects. Range: N/A
extra_dhcp_opts	Array of SubnetExtraDhcpOpt objects	Definition: DHCP attributes of a subnet. You can configure the NTP address, DNS domain name, or lease expiration time. Range: N/A.
created_at	String	Definition: Time when a subnet was created. Range: The value is a UTC time in the format of yyyy-MM-ddTHH:mm:ss.
updated_at	String	Definition: Time when a subnet was updated. Range: The value is a UTC time in the format of yyyy-MM-ddTHH:mm:ss.

**Table 5** SubnetCidr
Parameter	Type	Description
id	String	Definition: ID of the OpenStack Neutron subnet. Range: The value is in UUID format with hyphens (-).
ip_version	String	Definition: IP address version of the OpenStack Neutron subnet. Range: 4: IPv4 subnet. 6: IPv6 subnet.
cidr	String	Definition CIDR block of the OpenStack Neutron subnet. Range The value is in CIDR format and supports both IPv4 and IPv6 CIDR blocks. IPv4 CIDR block, for example, 192.168.23.0/24 IPv6 CIDR block, for example, 2420:2023:410:d5d::/64
gateway_ip	String	Definition: Gateway IP address of the OpenStack Neutron subnet. Range: N/A
enable_dhcp	Boolean	Definition: Whether the DHCP function is enabled for the OpenStack Neutron subnet. Range: true: The DHCP function is enabled. false: The DHCP function is disabled.

**Table 6** ResponseTag
Parameter	Type	Description
key	String	Definition: Tag key. Range: A tag key can contain a maximum of 128 Unicode characters and cannot be left blank. Each tag key of a resource must be unique. The value can contain: Letters Digits Special characters: underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and equal signs (=) Chinese characters
value	String	Definition: Tag value. Range: Each value can contain a maximum of 255 Unicode characters and can be left blank. The value can contain: Letters Digits Special characters: underscores (_), periods (.), colons (:), plus signs (+), hyphens (-), and equal signs (=) Chinese characters

**Table 7** SubnetExtraDhcpOpt
Parameter	Type	Description
opt_name	String	Definition: Name of the NTP server address, domain name, or DHCP lease expiration time configured for the subnet. Range: 42: NTP server address of the subnet. 15: DNS domain name, which is used to obtain the IP address from the DNS server. 51: DHCP lease expiration time of the IPv4 subnet. 651: DHCP lease expiration time of the IPv6 subnet.
opt_value	String	Definition: NTP server address, domain name, or DHCP lease expiration time configured for the subnet. Range: If opt_name is set to 42, the value indicates the NTP server address configured for the subnet. Currently, only IPv4 addresses are supported. A maximum of four IP addresses can be configured, and each address must be unique. Multiple IP addresses must be separated using commas (,). If opt_name is set to 15, the value is the DNS domain name and is used to obtain the IP address from the DNS server. A domain name can contain only letters, digits, and hyphens (-) and cannot start or end with a hyphen (-). A domain name can contain multiple character strings separated by periods (.). Each character string can contain up to 63 characters. The total length of a domain name cannot exceed 254 characters. The option 51 for opt_name indicates the DHCP lease expiration time of the IPv4 subnet. The value can be -1, which indicates unlimited lease time, or Numberh. The number ranges from 1 to 175200. For example, the value can be 5h. The default value is 87600h. The option 651 for opt_name indicates the DHCP lease expiration time of the IPv6 subnet. The value can be -1, which indicates unlimited lease time, or Numberh. The number ranges from 1 to 175200. For example, the value can be 5h. The default value is 2h.
ip_version	Integer	Definition: IP address version of a subnet. Range: 4: IPv4 (default value) 6: IPv6 (only when opt_name is 651)

**Table 8** PageInfo
Parameter	Type	Description
previous_marker	String	Definition: The first record on the current page. Range: N/A
current_count	Integer	Definition: Total number of resources on the current page. Range: N/A
next_marker	String	Definition: The last record on the current page. The next_marker field does not exist if the page is the last one. Range: N/A

Example Requests

Query subnets.

GET https://{Endpoint}/v3/{project_id}/vpc/virsubnets

Example Responses

Status code: 200

The GET operation is successful. For more status codes, see Status Codes.

{
  "request_id" : "83ce7c3aebc450bc40316e5856eff16e",
  "virsubnets" : [ {
    "name" : "subnet-1",
    "id" : "26c31230-6c2e-4dc3-b423-97ea75abac7c",
    "project_id" : "11e8dd119c77479db890e266e68c1ecf",
    "status" : "ACTIVE",
    "tags" : [ ],
    "description" : "",
    "created_at" : "2025-11-26T07:21:25",
    "updated_at" : "2025-12-05T09:11:19",
    "subnet_cidrs" : [ {
      "id" : "0ab40e38-edd2-46ff-bfec-d092d417275b",
      "ip_version" : "4",
      "cidr" : "192.168.23.0/24",
      "gateway_ip" : "192.168.23.1",
      "enable_dhcp" : true
    }, {
      "id" : "37fcba97-5fab-4328-906e-fc2b3f261796",
      "ip_version" : "6",
      "cidr" : "2420:2023:410:d5d::/64",
      "gateway_ip" : "2420:2023:410:d5d::1",
      "enable_dhcp" : true
    } ],
    "dns_nameservers" : [ "100.125.3.250", "100.125.3.251" ],
    "vpc_id" : "1e8a8ea6-c641-4461-810c-5851868f98be",
    "extra_dhcp_opts" : [ {
      "opt_value" : "10.0.0.1,10.0.0.2",
      "opt_name" : "42",
      "ip_version" : 4
    }, {
      "opt_value" : "2h",
      "opt_name" : "651",
      "ip_version" : 6
    }, {
      "opt_value" : "87600h",
      "opt_name" : "51",
      "ip_version" : 4
    }, {
      "opt_value" : "domain.com",
      "opt_name" : "15",
      "ip_version" : 4
    } ],
    "scope" : "center",
    "zone_id" : ""
  }, {
    "name" : "subnet-2",
    "id" : "518a60c6-06a1-427c-88b7-3e4fc98e2998",
    "project_id" : "11e8dd119c77479db890e266e68c1ecf",
    "status" : "ACTIVE",
    "tags" : [ {
      "key" : "a",
      "value" : "a"
    } ],
    "description" : "",
    "created_at" : "2025-11-14T03:57:02",
    "updated_at" : "2025-11-14T03:57:02",
    "subnet_cidrs" : [ {
      "id" : "eded5d66-4f57-4f9e-82f9-26796b00c526",
      "ip_version" : "4",
      "cidr" : "192.168.12.0/24",
      "gateway_ip" : "192.168.12.1",
      "enable_dhcp" : true
    } ],
    "dns_nameservers" : [ "100.125.3.250", "100.125.3.251" ],
    "vpc_id" : "a45cbb45-a36c-4d49-8616-0517aa158b14",
    "extra_dhcp_opts" : [ {
      "opt_value" : "87600h",
      "opt_name" : "51",
      "ip_version" : 4
    } ],
    "scope" : "center",
    "zone_id" : ""
  } ],
  "page_info" : {
    "previous_marker" : "26c31230-6c2e-4dc3-b423-97ea75abac7c",
    "current_count" : 2
  }
}

SDK Sample Code

The SDK sample code is as follows.

     package com.huaweicloud.sdk.test;

import com.huaweicloud.sdk.core.auth.ICredential;
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.vpc.v3.region.VpcRegion;
import com.huaweicloud.sdk.vpc.v3.*;
import com.huaweicloud.sdk.vpc.v3.model.*;


public class ListVirsubnetsSolution {

    public static void main(String[] args) {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        String ak = System.getenv("CLOUD_SDK_AK");
        String sk = System.getenv("CLOUD_SDK_SK");
        String projectId = "{project_id}";

        ICredential auth = new BasicCredentials()
                .withProjectId(projectId)
                .withAk(ak)
                .withSk(sk);

        VpcClient client = VpcClient.newBuilder()
                .withCredential(auth)
                .withRegion(VpcRegion.valueOf("<YOUR REGION>"))
                .build();
        ListVirsubnetsRequest request = new ListVirsubnetsRequest();
        try {
            ListVirsubnetsResponse response = client.listVirsubnets(request);
            System.out.println(response.toString());
        } catch (ConnectionException e) {
            e.printStackTrace();
        } catch (RequestTimeoutException e) {
            e.printStackTrace();
        } catch (ServiceResponseException e) {
            e.printStackTrace();
            System.out.println(e.getHttpStatusCode());
            System.out.println(e.getRequestId());
            System.out.println(e.getErrorCode());
            System.out.println(e.getErrorMsg());
        }
    }
}
 
 
  

     # coding: utf-8

import os
from huaweicloudsdkcore.auth.credentials import BasicCredentials
from huaweicloudsdkvpc.v3.region.vpc_region import VpcRegion
from huaweicloudsdkcore.exceptions import exceptions
from huaweicloudsdkvpc.v3 import *

if __name__ == "__main__":
    # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak = os.environ["CLOUD_SDK_AK"]
    sk = os.environ["CLOUD_SDK_SK"]
    projectId = "{project_id}"

    credentials = BasicCredentials(ak, sk, projectId)

    client = VpcClient.new_builder() \
        .with_credentials(credentials) \
        .with_region(VpcRegion.value_of("<YOUR REGION>")) \
        .build()

    try:
        request = ListVirsubnetsRequest()
        response = client.list_virsubnets(request)
        print(response)
    except exceptions.ClientRequestException as e:
        print(e.status_code)
        print(e.request_id)
        print(e.error_code)
        print(e.error_msg)
 
 
  

     package main

import (
	"fmt"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
    vpc "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/vpc/v3"
	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/vpc/v3/model"
    region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/vpc/v3/region"
)

func main() {
    // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
    // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
    ak := os.Getenv("CLOUD_SDK_AK")
    sk := os.Getenv("CLOUD_SDK_SK")
    projectId := "{project_id}"

    auth, err := basic.NewCredentialsBuilder().
        WithAk(ak).
        WithSk(sk).
        WithProjectId(projectId).
        SafeBuild()

    if err != nil {
        fmt.Println(err)
        return
    }

    hcClient, err := vpc.VpcClientBuilder().
         WithRegion(region.ValueOf("<YOUR REGION>")).
         WithCredential(auth).
         SafeBuild()


    if err != nil {
        fmt.Println(err)
        return
    }

    client := vpc.NewVpcClient(hcClient)

    request := &model.ListVirsubnetsRequest{}
	response, err := client.ListVirsubnets(request)
	if err == nil {
        fmt.Printf("%+v\n", response)
    } else {
        fmt.Println(err)
    }
}
 
 
  