Query and Filter EIPs via DescribeEipAddresses API - Elastic IP Address - Alibaba Cloud - Elastic IP Address

Queries the elastic IP addresses (EIPs) created in a specified region.

Operation description

This operation queries the information about elastic IP addresses (EIPs) created in a specified region, including the peak bandwidth, billing method, and currently attached instance type. If you frequently skip pages during deep paging, the Throttling.DeepPageSkip error code may be returned. Reduce the query frequency or use sequential paging.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

vpc:DescribeEipAddresses

list

*Address

acs:vpc:{#regionId}:{#accountId}:eip/*

vpc:tag

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the EIP. You can call the DescribeRegions operation to query the region ID.	cn-hangzhou
IncludeReservationData	boolean	No	Specifies whether to include inactive subscription data. Valid values: false (default): Does not include inactive subscription data. true: Includes inactive subscription data.	false
Status	string	No	The status of the EIP. Valid values: Associating: The EIP is being associated. Unassociating: The EIP is being disassociated. InUse: The EIP is allocated. Available: The EIP is available. Releasing: The EIP is being released.	Available
EipAddress	string	No	The IP address of the EIP to query. You can enter up to 50 EIP addresses. Separate multiple IP addresses with commas (,). Note If you specify both EipAddress and AllocationId, you can enter up to 50 EIP addresses for EipAddress and up to 50 EIP instance IDs for AllocationId.	47.75.XX.XX
AllocationId	string	No	The ID of the EIP to query. You can enter up to 50 EIP instance IDs. Separate multiple instance IDs with commas (,). Note If you specify both EipAddress and AllocationId, you can enter up to 50 EIP instance IDs for AllocationId and up to 50 EIP addresses for EipAddress.	eip-2zeerraiwb7ujxscd****
SegmentInstanceId	string	No	The instance ID of the contiguous EIP.	eipsg-t4nr90yik5oy38xdy****
ResourceGroupId	string	No	The ID of the resource group to which the EIP belongs.	rg-acfmxazb4pcdvf****
PageNumber	integer	No	The page number of the list. Default value: 1.	10
PageSize	integer	No	The number of entries per page for a paged query. Maximum value: 100. Default value: 10.	10
ISP	string	No	The line type. Valid values: BGP (default): BGP (multi-ISP) line. BGP (multi-ISP) EIPs are supported in all regions. BGP_PRO: BGP (multi-ISP) Pro line. BGP (multi-ISP) Pro EIPs are supported only in the Hong Kong (China), Singapore, Japan (Tokyo), Malaysia (Kuala Lumpur), Philippines (Manila), Indonesia (Jakarta), and Thailand (Bangkok) regions. For more information about BGP (multi-ISP) and BGP (multi-ISP) Pro lines, see EIP line types. If you are a whitelisted user for single-ISP bandwidth, you can also select the following types: ChinaTelecom: China Telecom ChinaUnicom: China Unicom ChinaMobile: China Mobile ChinaTelecom_L2: China Telecom L2 ChinaUnicom_L2: China Unicom L2 ChinaMobile_L2: China Mobile L2 If you are an Alibaba Finance Cloud user in the China (Hangzhou) region, this parameter is required. Set the value to BGP_FinanceCloud.	BGP
Filter.1.Key	string	No	The filter key used when querying resources. Set the value to CreationStartTime, which specifies the start time of resource creation.	CreationStartTime
Filter.2.Key	string	No	The filter key used when querying resources. Set the value to CreationEndTime, which specifies the end time of resource creation.	CreationEndTime
Filter.1.Value	string	No	The filter value used when querying resources. Specify the time in UTC in the `YYYY-MM-DDThh:mmZ` format.	2023-01-01T01:00Z
Filter.2.Value	string	No	The filter value used when querying resources. Specify the time in UTC in the `YYYY-MM-DDThh:mmZ` format.	2023-01-06T02:00Z
LockReason	string	No	The lock type. Valid values: financial: The EIP is locked due to an overdue payment. security: The EIP is locked due to security reasons.	financial
AssociatedInstanceType	string	No	The type of the cloud service instance to attach to the EIP. Valid values: EcsInstance (default): an ECS instance in a VPC. SlbInstance: a CLB instance in a VPC. Nat: a NAT gateway. HaVip: a high-availability virtual IP address. NetworkInterface: a secondary elastic network interface controller (NIC). IpAddress: an IP address. Note You can attach only one EIP to each ECS instance, CLB instance, high-availability virtual IP address, or IP address at a time. You can attach multiple EIPs to a NAT gateway. The number of EIPs that can be attached to a secondary elastic network interface controller (NIC) depends on the EIP attach pattern. For more information, see Overview of elastic IP addresses.	EcsInstance
AssociatedInstanceId	string	No	The instance ID of the cloud service.	i-2zebb08phyccdvf****
ChargeType	string	No	The billing method of the EIP. Valid values: PostPaid: pay-as-you-go. PrePaid: subscription.	PostPaid
DryRun	boolean	No	Specifies whether to only precheck the request. Valid values: true: sends a check request and does not query the resource status. The system checks whether required parameters are specified, the request format is valid, and the service limits are met. If the request fails the check, the corresponding error is returned. If the request passes the check, the `DryRunOperation` error code is returned. false (default): sends a regular request. After the request passes the check, the system returns an HTTP 2xx status code and performs the operation.	false
EipName	string	No	The name of the EIP. The name must be 1 to 128 characters in length, and must start with a letter or a Chinese character. It can contain digits, underscores (_), and hyphens (-).	EIP-01
Tag	array<object>	No	The tags used to filter EIPs.
	object	No	The tags used to filter EIPs.
Key	string	No	The tag key. You can enter up to 20 tag keys. If you specify this parameter, it cannot be an empty string. A tag key can be up to 128 characters in length. It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceDept
Value	string	No	The tag value. You can enter up to 20 tag values. If you specify this parameter, it can be an empty string. A tag value can be up to 128 characters in length. It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceJoshua
SecurityProtectionEnabled	boolean	No	Specifies whether Anti-DDoS (Enhanced) is enabled. Valid values: false: Anti-DDoS (Enhanced) is disabled. true: Anti-DDoS (Enhanced) is enabled.	false
PublicIpAddressPoolId	string	No	The ID of the IP address pool to which the EIP to query belongs.	pippool-2vc0kxcedhquybdsz****
ServiceManaged	boolean	No	Specifies whether the instance is a managed instance. Valid values: true: The instance is a managed instance. false: The instance is not a managed instance. If you do not specify this parameter, all instances are queried by default.	false

Response elements

Element	Type	Description	Example
	object	The list of returned information.
PageSize	integer	The number of entries per page.	10
RequestId	string	The request ID.	4EC47282-1B74-4534-BD0E-403F3EE64CAF
PageNumber	integer	The current page number.	10
TotalCount	integer	The total number of entries.	1
EipAddresses	object
EipAddress	array<object>	The details of the EIPs.
	array<object>	The details of the EIPs.
ReservationActiveTime	string	The effective period of the renewal, in the `YYYY-MM-DDThh:mm:ssZ` format.	2021-05-23T16:00:00Z
Status	string	The status of the EIP. Valid values: Associating: associating Unassociating: disassociating InUse: allocated Available: available Releasing: releasing	Available
ReservationOrderType	string	The renewal order type. Valid values: RENEWCHANGE: renewal with specification change TEMP_UPGRADE: temporary upgrade UPGRADE: upgrade	RENEWCHANGE
AllocationTime	string	The creation time of the EIP, in the `YYYY-MM-DDThh:mm:ssZ` format.	2021-04-23T01:37:38Z
Netmode	string	The network type. Only public is returned, which indicates the Internet.	public
ChargeType	string	The billing pattern of the EIP. Valid values: PostPaid: pay-as-you-go billing method. PrePaid: subscription.	PostPaid
Description	string	The description of the EIP.	abc
Mode	string	The association mode. Valid values: NAT: NAT mode (normal mode) MULTI_BINDED: multi-EIP to ENI mode BINDED: EIP to ENI mode	NAT
SegmentInstanceId	string	The instance ID of the contiguous EIP. This parameter is returned only when the EIP is a contiguous EIP.	eipsg-t4nr90yik5oy38xd****
ReservationInternetChargeType	string	The renewal billing type. Valid values: PayByBandwidth: pay-by-bandwidth PayByTraffic: pay-by-data-transfer	PayByBandwidth
BandwidthPackageId	string	The ID of the Internet Shared Bandwidth instance to which the EIP is added.	cbwp-bp1ego3i4j07ccdvf****
IpAddress	string	The IP address of the EIP.	47.75.XX.XX
Bandwidth	string	The maximum bandwidth of the EIP. Unit: Mbit/s.	5
ReservationBandwidth	string	The renewal bandwidth. Unit: Mbit/s.	12
EipBandwidth	string	The bandwidth of the EIP before it is added to an Internet Shared Bandwidth instance or after it is removed from an Internet Shared Bandwidth instance. Unit: Mbit/s.	101
Name	string	The name of the EIP.	EIP-01
PrivateIpAddress	string	The private IP address of the secondary elastic network interface controller (NIC) instance to which the EIP is attached.	192.168.XX.XX
InstanceRegionId	string	The region ID of the associated resource.	cn-hangzhou
DeletionProtection	boolean	Indicates whether deletion protection is enabled. Valid values: true: enabled false: disabled	true
InstanceId	string	The ID of the associated instance.	i-bp15zckdt37cdvf****
SecondLimited	boolean	Indicates whether secondary bandwidth throttling is configured. Valid values: true: configured false: not configured	false
InstanceType	string	The type of the attached instance. Valid values: EcsInstance: an ECS instance in a VPC SlbInstance: a CLB instance in a VPC Nat: a NAT gateway HaVip: a high-availability virtual IP address NetworkInterface: a secondary elastic network interface controller (NIC) IpAddress: an IP address	EcsInstance
HDMonitorStatus	string	Indicates whether second-level monitoring is enabled for the EIP. Valid values: false: disabled true: enabled	false
RegionId	string	The region ID of the EIP.	cn-hangzhou
BandwidthPackageBandwidth	string	The bandwidth of the Internet Shared Bandwidth instance to which the EIP is added. Unit: Mbit/s.	50
ServiceManaged	integer	Indicates whether the instance is a managed instance. Valid values: 1: yes 0: no	0
ExpiredTime	string	The expiration time, in the `YYYY-MM-DDThh:mm:ssZ` format.	2021-05-23T02:00:00Z
ResourceGroupId	string	The resource group ID.	rg-acfmxazcdxs****
AllocationId	string	The instance ID of the EIP.	eip-2zeerraiwb7ujcdvf****
InternetChargeType	string	The billing method of the EIP. Valid values: PayByBandwidth: pay-by-bandwidth PayByTraffic: pay-by-data-transfer	PayByBandwidth
BusinessStatus	string	The service status of the EIP. Valid values: Normal: normal OperationLock: locked Unactivated: not activated	Normal
BandwidthPackageType	string	The type of the bandwidth. Only CommonBandwidthPackage (Internet Shared Bandwidth) is returned.	CommonBandwidthPackage
HasReservationData	string	Indicates whether renewal data exists. Valid values: false: no renewal data exists true: renewal data exists. This value is returned only when the IncludeReservationData request parameter is set to true and inactive subscription data exists.	false
ISP	string	The line type. Valid values: BGP: BGP (multi-ISP) line. EIPs of BGP (multi-ISP) lines are supported in all regions. BGP_PRO: BGP (multi-ISP) Pro line. EIPs of BGP (multi-ISP) Pro lines are supported only in the Hong Kong (China), Singapore, Japan (Tokyo), Malaysia (Kuala Lumpur), Philippines (Manila), Indonesia (Jakarta), and Thailand (Bangkok) regions. For more information about BGP (multi-ISP) and BGP (multi-ISP) Pro lines, see EIP line types. If you are a single-ISP bandwidth whitelist user, the following values may also be returned: ChinaTelecom: China Telecom ChinaUnicom: China Unicom ChinaMobile: China Mobile ChinaTelecom_L2: China Telecom L2 ChinaUnicom_L2: China Unicom L2 ChinaMobile_L2: China Mobile L2 If you are an Alibaba Finance Cloud user in the China (Hangzhou) region, BGP_FinanceCloud is returned.	BGP
OperationLocks	object
LockReason	array<object>	The lock details.
	object	The lock details.
LockReason	string	The lock type. Valid values: financial: locked due to overdue payments security: locked due to security reasons sharedPool: locked due to overdue payments of the shared IP address pool	financial
Tags	object
Tag	array<object>	The list of tags of the EIP.
	object	The list of tags of the EIP.	"Tag": [ { "Value": "000", "Key": "yyy" }, { "Value": "111","Key": "kkk" }
Key	string	The tag key of the EIP.	KeyTest
Value	string	The tag value of the EIP.	ValueTest
SecurityProtectionTypes	object
SecurityProtectionType	array	The security protection level. Valid values: An empty value indicates Anti-DDoS Basic. AntiDDoS_Enhanced: Anti-DDoS (Enhanced)
	string	The security protection level. Valid values: An empty value indicates Anti-DDoS Basic. AntiDDoS_Enhanced: Anti-DDoS (Enhanced)	AntiDDoS_Enhanced
PublicIpAddressPoolId	string	The ID of the IP address pool to which the EIP belongs.	pippool-2vc0kxcedhquybdsz****
VpcId	string	The ID of the VPC that has the IPv4 gateway feature enabled and resides in the same region as the EIP. When the EIP is attached to an IP address, the system can enable public network access for the attached IP address based on the routing configurations of this VPC. Note This parameter is returned when InstanceType is set to IpAddress, which means the EIP is attached to an IP address.	vpc-bp15zckdt37pq72zv****
Zone	string	The zone of the EIP. This parameter is returned only when the service type of the EIP is CloudBox.	ap-southeast-1-lzdvn-cb
BizType	string	The service type of the EIP. Valid values: CloudBox: CloudBox. This type is supported only for CloudBox users. Default: the default value, which indicates a standard type.	CloudBox
ServiceID	integer	The ID of the managed account for the cloud service.	18726XXXXXXX

Examples

Success response

JSON format

{
  "PageSize": 10,
  "RequestId": "4EC47282-1B74-4534-BD0E-403F3EE64CAF",
  "PageNumber": 10,
  "TotalCount": 1,
  "EipAddresses": {
    "EipAddress": [
      {
        "ReservationActiveTime": "2021-05-23T16:00:00Z",
        "Status": "Available",
        "ReservationOrderType": "RENEWCHANGE",
        "AllocationTime": "2021-04-23T01:37:38Z",
        "Netmode": "public",
        "ChargeType": "PostPaid",
        "Description": "abc",
        "Mode": "NAT",
        "SegmentInstanceId": "eipsg-t4nr90yik5oy38xd****",
        "ReservationInternetChargeType": "PayByBandwidth",
        "BandwidthPackageId": "cbwp-bp1ego3i4j07ccdvf****",
        "IpAddress": "47.75.XX.XX",
        "Bandwidth": "5",
        "ReservationBandwidth": "12",
        "EipBandwidth": "101",
        "Name": "EIP-01",
        "PrivateIpAddress": "192.168.XX.XX",
        "InstanceRegionId": " cn-hangzhou",
        "DeletionProtection": true,
        "InstanceId": "i-bp15zckdt37cdvf****",
        "SecondLimited": false,
        "InstanceType": "EcsInstance",
        "HDMonitorStatus": "false",
        "RegionId": "cn-hangzhou",
        "BandwidthPackageBandwidth": "50",
        "ServiceManaged": 0,
        "ExpiredTime": "2021-05-23T02:00:00Z",
        "ResourceGroupId": "rg-acfmxazcdxs****",
        "AllocationId": "eip-2zeerraiwb7ujcdvf****",
        "InternetChargeType": "PayByBandwidth",
        "BusinessStatus": "Normal",
        "BandwidthPackageType": "CommonBandwidthPackage",
        "HasReservationData": "false",
        "ISP": "BGP",
        "OperationLocks": {
          "LockReason": [
            {
              "LockReason": "financial"
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "Key": "KeyTest",
              "Value": "ValueTest"
            }
          ]
        },
        "SecurityProtectionTypes": {
          "SecurityProtectionType": [
            "AntiDDoS_Enhanced"
          ]
        },
        "PublicIpAddressPoolId": "pippool-2vc0kxcedhquybdsz****",
        "VpcId": "vpc-bp15zckdt37pq72zv****",
        "Zone": "ap-southeast-1-lzdvn-cb",
        "BizType": "CloudBox",
        "ServiceID": 0
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidIAssociatedInstanceType.ValueNotSupported	The specified value of AssociatedInstanceType is not supported.	The AssociatedInstanceType parameter is set to an invalid value.
400	InvalidChargeType.ValueNotSupported	The specified ChargeType is not supported.
400	InvalidAliuid	User Id is not valid.
400	InvalidResourceGroupId	The specified ResourceGroupId does not exist.	The specified resource group ID does not exist.
400	InstanceType.Invalid	InstanceType is not null
400	InstanceIdLength.Exceed	InstanceId length is exceed
400	InvalidTagKey	The tag keys are not valid.	The tag index is invalid.
400	InvalidTagValue	The tag values are not valid.	The tag value is invalid.
400	OperationUnsupported.ResourceGroupId	ResourceGroup is not supported in this region.	The resource group feature is not enabled.
400	IellgalParameter.OwnerAccount	The specified parameter OwnerAccount is not valid.	The specified parameter OwnerAccount is illegal.
400	Throttling.DeepPageSkip	Deep page skip throttled. Please reduce the page skip frequency or use sequential pagination.	The number of deep pagination skip operations has triggered rate limiting. Reduce the frequency of deep page jumps, or use sequential paging.
404	InvalidFilterValue	The specified FilterValue is not supported.
404	Forbidden.RegionNotFound	Specified region is not found during access authentication.
404	InvalidFilterKey.NotFound	The specified Filterkey is not supported.
404	InvalidLockReason.NotFound	The specified LockReason is not found

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.