Updated on 2026-09-01 GMT+08:00

Obtaining Available IP Addresses of a Network

Function

This API is used to obtain available IP addresses on a specified network. Use this API when you need to quickly obtain available IP addresses during network planning, resource allocation, or troubleshooting. Before calling this API, ensure that you have the permissions to access the target network and the network range (such as the subnet mask or IP address segment) is valid. After this API is called, the system returns a list of available IP addresses on the specified network. You can assign IP addresses or perform further operations based on the results. If the network is unreachable, you do not have the required permissions, or the network range is incorrect, an error message is returned.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

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, no identity policy-based permission required for calling this API.

URI

GET /v1/{project_id}/networks/{network_name}/network-ip-availabilities

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: Project ID. For details, see Obtaining a Project ID and Name. Constraints: The value can contain 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed. Range: N/A Default Value: N/A
network_name	Yes	String	Definition: Network ID. To obtain the value, see the metadata.name field in network details. Constraints: The value can contain 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed. Range: N/A Default Value: N/A

**Table 2** Query Parameters
Parameter	Mandatory	Type	Description
network_id	Yes	String	Definition: Subnet ID. To obtain the value, see the networkId field in status.subnets of the network details. Constraints: The value can contain 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed. Range: N/A Default Value: N/A

Request Parameters

None

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
name	String	Definition: Subnet name. Range: N/A
networkId	String	Definition: Subnet ID. Range: N/A
subnetIpAvailability	Array of SubnetIpAvailability objects	Definition: Number of available network IP addresses of the subnet.

**Table 4** SubnetIpAvailability
Parameter	Type	Description
cidr	String	Definition: Subnet CIDR. Range: N/A
ipVersion	Integer	Definition: Network version. Range: 4: IPv4
usedIps	Integer	Definition: Number of used IP addresses. Range: N/A
totalIps	Integer	Definition: Total number of IP addresses in the subnet. Range: N/A

Status code: 404

**Table 5** Response body parameters
Parameter	Type	Description
error_code	String	Definition: ModelArts error code. Range: N/A
error_msg	String	Definition: Error message. Range: N/A

Example Requests

Obtain the number of available IP addresses of a network.

GET https://{endpoint}/v1/{project_id}/networks/{network_name}/network-ip-availabilities?network_id={network_id}

Example Responses

Status code: 200

Succeeded.

{
  "name" : "default-subnet",
  "networkId" : "2526defb-8b30-4fa9-82ab-e7dde66ef16a",
  "subnetIpAvailability" : [ {
    "cidr" : "172.18.0.0/16",
    "ipVersion" : 4,
    "usedIps" : 13,
    "totalIps" : 65531
  } ]
}

Status code: 404

Not found.

{
  "error_code" : "ModelArts.50025001",
  "error_msg" : "Network not exist."
}

Status Codes

Status Code	Description
200	Succeeded.
404	Not found.

Error Codes

See Error Codes.

Parent topic: Resource Management