Help Center/ Elastic Cloud Server/ API Reference/ APIs/ NIC Management/ Querying the NICs That Can Be Attached to An ECS
Updated on 2025-09-19 GMT+08:00

Querying the NICs That Can Be Attached to An ECS

Function

This API is used to query the NICs that can be attached to an ECS.

URI

GET /v1/{project_id}/cloudservers/{server_id}/os-interface_extension

Table 1 describes the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

For details about how to obtain the ID, see Obtaining a Project ID.

server_id

Yes

Specifies the ECS ID.

Request

None.

Response

Table 2 describes the response parameter.

Table 2 Response parameters

Parameter

Type

Description

attachableQuantity

Object

Definition

Specifies the number of NICs that can be attached to an ECS. For details, see Table 3.

Range

N/A

interfaceAttachments

Array of objects

Definition

Specifies the NIC information list. For details, see Table 4.

Range

N/A

Table 3 attachableQuantity field description

Parameter

Type

Description

free_efi_nic

String

Definition

Specifies the remaining number of EFI NICs that can be attached to an ECS.

Range

N/A

Table 4 interfaceAttachments field description

Parameter

Type

Description

port_state

String

Definition

Specifies the NIC port status.

Range

N/A

fixed_ips

Array of objects

Definition

Specifies the private IP address list for NICs. For details, see Table 5.

Range

N/A

net_id

String

Definition

Specifies the network ID (network_id) that the NIC port belongs to.

Range

N/A

port_id

String

Definition

Specifies the ID of the NIC port.

Range

N/A

mac_addr

String

Definition

Specifies the MAC address of the NIC.

Range

N/A

delete_on_termination

Boolean

Definition

Specifies whether to delete a NIC when detaching it.

Range

  • true: Delete the NIC.
  • false: Do not delete the NIC.

driver_mode

String

Definition

Specifies the NIC driver type, which is virtio by default. This parameter is a reserved field.

Range

N/A

min_rate

Integer

Definition

Specifies the minimum NIC bandwidth.

Range

N/A

multiqueue_num

Integer

Definition

Specifies the number of queues.

Range

1~64

pci_address

String

Definition

Specifies the BDF number of the elastic network interface in Linux GuestOS.

NOTE:

If the elastic network interface is not supported, no information will be returned.

Range

N/A

preserve_on_delete

Boolean

Definition

Specifies whether to retain the NIC when it is deleted.

Range

  • true: Retain the NIC.
  • false: Do not retain the NIC.
Table 5 fixed_ips field description

Parameter

Type

Description

subnet_id

String

Definition

Specifies the subnet of the NIC private IP address.

Range

N/A

ip_address

String

Definition

Specifies the NIC private IP address.

Range

N/A

Example Request

Query the NICs that can be attached to an ECS.

GET https://{endpoint}/v1/{project_id}/cloudservers/{server_id}/os-interface_extensione

Example Response

{
    "attachableQuantity": {
        "free_efi_nic": 0
    },
    "interfaceAttachments": [
        {
            "port_state": "ACTIVE",
            "fixed_ips": [
                {
                    "subnet_id": "ba31e1f5-fa76-4530-862c-5176fad033cf",
                    "ip_address": "192.168.0.33"
                }
            ],
            "net_id": "610a4af2-1d90-4d2b-8057-dc238b26febf",
            "port_id": "04819c0a-6a07-44b6-945e-fb932071888e",
            "mac_addr": "fa:16:3e:45:65:c4",
            "delete_on_termination": false,
			"preserve_on_delete": false,
            "driver_mode": null,
            "min_rate": null,
            "multiqueue_num": null,
            "pci_address": null
        }
    ]
}

Error Codes

See Error Codes.