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

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

Operation description

This operation queries information about EIPs created in a specified region, including the maximum bandwidth, billing method, and the type of instance currently attached to each EIP. If you frequently perform deep paging or page skipping, the Throttling.DeepPageSkip error code may be returned. Reduce the query frequency or use sequential pagination.

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.	cn-hangzhou
IncludeReservationData	boolean	No	Specifies whether to include subscription data that has not taken effect. Valid values:	false
Status	string	No	The status of the EIP. Valid values:	Available
EipAddress	string	No	The IP address of the EIP to query.	47.75.XX.XX
AllocationId	string	No	The ID of the EIP instance to query.	eip-2zeerraiwb7ujxscd****
SegmentInstanceId	string	No	The instance ID of the contiguous EIP group.	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 in a paged query. Maximum value: 100. Default value: 10.	10
ISP	string	No	The line type. Valid values:	BGP
Filter.1.Key	string	No	The filter key for querying resources. The value must be CreationStartTime, which specifies the start time when the resource was created.	CreationStartTime
Filter.2.Key	string	No	The filter key for querying resources. The value must be CreationEndTime, which specifies the end time when the resource was created.	CreationEndTime
Filter.1.Value	string	No	The filter value for querying resources. Specify the value in UTC in the `YYYY-MM-DDThh:mmZ` format.	2023-01-01T01:00Z
Filter.2.Value	string	No	The filter value for querying resources. Specify the value in UTC in the `YYYY-MM-DDThh:mmZ` format.	2023-01-06T02:00Z
LockReason	string	No	The lock type. Valid values:	financial
AssociatedInstanceType	string	No	The type of the cloud resource instance to be associated. Valid values:	EcsInstance
AssociatedInstanceId	string	No	The instance ID of the cloud resource.	i-2zebb08phyccdvf****
ChargeType	string	No	The billing method of the EIP. Valid values:	PostPaid
DryRun	boolean	No	Specifies whether to perform only a dry run. Valid values:	false
EipName	string	No	The name of the EIP.	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 specify up to 20 tag keys. The tag key cannot be an empty string.	FinanceDept
Value	string	No	The tag value. You can specify up to 20 tag values. The tag value can be an empty string.	FinanceJoshua
SecurityProtectionEnabled	boolean	No	Specifies whether Anti-DDoS (Enhanced) is enabled. Valid values:	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:	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 EIP.
	array<object>	The details of the EIP.
ReservationActiveTime	string	The renewal active time in the format of `YYYY-MM-DDThh:mm:ssZ`.	2021-05-23T16:00:00Z
Status	string	The status of the EIP.	Available
ReservationOrderType	string	The renewal order type.	RENEWCHANGE
AllocationTime	string	The time when the EIP was created in the format of `YYYY-MM-DDThh:mm:ssZ`.	2021-04-23T01:37:38Z
Netmode	string	The network type. The value is public, which indicates the Internet.	public
ChargeType	string	The billing method of the EIP. Valid values:	PostPaid
Description	string	The description of the EIP.	abc
Mode	string	The association mode. Valid values:	NAT
SegmentInstanceId	string	The instance ID of the contiguous EIP group.	eipsg-t4nr90yik5oy38xd****
ReservationInternetChargeType	string	The renewal billing type.	PayByBandwidth
BandwidthPackageId	string	The ID of the Internet Shared Bandwidth instance that the EIP is added to.	cbwp-bp1ego3i4j07ccdvf****
IpAddress	string	The IP address of the EIP.	47.75.XX.XX
Bandwidth	string	The peak bandwidth of the EIP. Unit: Mbps.	5
ReservationBandwidth	string	The renewal bandwidth. Unit: Mbps.	12
EipBandwidth	string	The bandwidth of the EIP before it is added to or after it is removed from an Internet Shared Bandwidth instance. Unit: Mbps.	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 that the EIP is attached to.	192.168.XX.XX
InstanceRegionId	string	The region ID of the resource that is currently associated with the EIP.	cn-hangzhou
DeletionProtection	boolean	Indicates whether deletion protection is enabled.	true
InstanceId	string	The ID of the instance that is currently associated with the EIP.	i-bp15zckdt37cdvf****
SecondLimited	boolean	Indicates whether secondary bandwidth throttling is configured.	false
InstanceType	string	The type of the instance that is currently associated with the EIP.	EcsInstance
HDMonitorStatus	string	Indicates whether second-level monitoring is enabled for the EIP.	false
RegionId	string	The region ID of the EIP.	cn-hangzhou
BandwidthPackageBandwidth	string	The bandwidth of the Internet Shared Bandwidth instance that the EIP is added to. Unit: Mbps.	50
ServiceManaged	integer	Specifies whether the instance is a managed instance. Valid values:	0
ExpiredTime	string	The expiration time in the format of `YYYY-MM-DDThh:mm:ssZ`.	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.	PayByBandwidth
BusinessStatus	string	The business status of the EIP instance.	Normal
BandwidthPackageType	string	The bandwidth type. Only CommonBandwidthPackage (Internet Shared Bandwidth) is returned.	CommonBandwidthPackage
HasReservationData	string	Indicates whether renewal data exists.	false
ISP	string	The line type.	BGP
OperationLocks	object
LockReason	array<object>	The lock details.
	object	The lock details.
LockReason	string	The lock type.	financial
Tags	object
Tag	array<object>	The list of tags associated with the EIP.
	object	The list of tags associated with 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.
	string	The security protection level.	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 is in the same region as the EIP.	vpc-bp15zckdt37pq72zv****
Zone	string	The zone of the EIP.	ap-southeast-1-lzdvn-cb
BizType	string	The business type of the EIP.	CloudBox
ServiceID	integer	The ID of the cloud service managed account.	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 operation is not supported. Resource group IDs are not supported in Finance Cloud.
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.