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

Usage notes

You can call this operation to query the information about EIPs in a specified region, including the maximum bandwidth, billing methods, and associated instances.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeEipAddresses

The operation that you want to perform. Set the value to DescribeEipAddresses.

RegionId String Yes cn-hangzhou

The region ID of the EIP.

You can call the DescribeRegions operation to query the most recent region list.

IncludeReservationData Boolean No false

Specifies whether to return information about pending orders. Valid values:

  • false (default): does not return information about pending orders.
  • true: returns information about pending orders.
Status String No Available

The status of the EIP. Valid values:

  • Associating: being associated
  • Unassociating: being disassociated
  • InUse: allocated
  • Available: available
  • Releasing: being released
EipAddress String No 47.75.XX.XX

The IP address of the EIP that you want to query.

You can enter up to 50 IP addresses of EIPs. Separate multiple IP addresses with commas (,).

Note If both the EipAddress and AllocationId parameters are set, you can enter up to 50 IP addresses of EIPs in EipAddress, and enter up to 50 IDs of EIPs in AllocationId.
AllocationId String No eip-2zeerraiwb7ujxscd****

The ID of the EIP that you want to query.

You can enter up to 50 IDs of EIPs. Separate multiple IDs with commas (,).

Note If both the EipAddress and AllocationId parameters are set, you can enter up to 50 IDs of EIPs in AllocationId, and enter up to 50 IP addresses of EIPs in EipAddress.
SegmentInstanceId String No eipsg-t4nr90yik5oy38xdy****

The IDs of the contiguous EIPs.

ResourceGroupId String No rg-acfmxazb4pcdvf****

The ID of the resource group to which the EIPs belong.

PageNumber Integer No 10

The number of the page to return. Default value: 1.

PageSize Integer No 10

The number of entries to return on each page. Maximum value: 100. Default value: 10.

ISP String No BGP

The line type. Valid values:

  • BGP (default): BGP (Multi-ISP) lines. All regions support BGP (Multi-ISP) EIPs.
  • BGP_PRO: BGP (Multi-ISP) Pro lines. Only the following regions support BGP (Multi-ISP) Pro lines: China (Hong Kong), Singapore, Malaysia (Kuala Lumpur), Philippines (Manila), Indonesia (Jakarta), and Thailand (Bangkok).

For more information about BGP (Multi-ISP) and BGP (Multi-ISP) Pro, see EIP line types.

If you are allowed to use single-ISP bandwidth, you can also choose one of the following values:

  • 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 your services are deployed in China East 1 Finance, you must set this parameter to BGP_FinanceCloud.

Filter.1.Key String No CreationStartTime

The filter key used to query resources. Set the value to CreationStartTime, which indicates the time when the system started to create the resource.

Filter.2.Key String No CreationEndTime

The filter key used to query resources. Set the value to CreationEndTime, which indicates the time when the system completed creating the resource.

Filter.1.Value String No 2023-01-01T01:00Z

The filter value used to query resources. Specify the time in the ISO 8601 standard in YYYY-MM-DDThh:mmZ format. The time must be in UTC.

Filter.2.Value String No 2023-01-06T02:00Z

The filter value used to query resources. Specify the time in the ISO 8601 standard in YYYY-MM-DDThh:mmZ format. The time must be in UTC.

LockReason String No financial

The reason why the EIP is locked. Valid values:

  • financial: The EIP is locked due to overdue payments.
  • security: The EIP is locked for security reasons.
AssociatedInstanceType String No EcsInstance

The type of the cloud resource with which you want to associate the EIP. Valid values:

  • EcsInstance (default): an Elastic Compute Service (ECS) instance in a virtual private cloud (VPC)
  • SlbInstance: a Server Load Balancer (SLB) instance in a VPC
  • Nat: a NAT gateway
  • HaVip: a high-availability virtual IP address (HAVIP)
  • NetworkInterface: a secondary ENI
  • IpAddress: an IP address
Note You can associate only one EIP with each ECS instance, SLB instance, HAVIP, or IP address. You can associate multiple EIPs with each NAT gateway. The number of EIPs that you can associate with a secondary ENI depends on the association mode. For more information, see EIP overview.
AssociatedInstanceId String No i-2zebb08phyccdvf****

The ID of the cloud resource.

ChargeType String No PostPaid

The billing method of the EIP. Valid values:

  • PostPaid: pay-as-you-go
  • PrePaid: subscription
DryRun Boolean No false

Specifies whether to perform a dry run. Valid values:

  • true: performs a dry run. The system checks the required parameters, request syntax, and limits. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned.
  • false (default): performs a dry run and sends the request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed.
EipName String No EIP-01

The name of the EIP.

The name must be 1 to 128 characters in length, and can contain letters, digits, underscores (_), and hyphens (-). The name must start with a letter.

SecurityProtectionEnabled Boolean No false

Specifies whether to enable Anti-DDoS Pro/Premium. Valid values:

  • false (default): no
  • true: yes
PublicIpAddressPoolId String No pippool-2vc0kxcedhquybdsz****

The IP address pool to which the EIP that you want to query belongs.

Response parameters

Parameter Type Example Description
PageSize Integer 10

The number of entries returned per page.

RequestId String 4EC47282-1B74-4534-BD0E-403F3EE64CAF

The ID of the request.

PageNumber Integer 10

The page number of the returned page.

TotalCount Integer 1

The total number of entries returned.

EipAddresses Array of EipAddress

The details about the EIP.

EipAddress
ReservationActiveTime String 2021-05-23T16:00:00Z

The time when the renewal takes effect. The time is displayed in YYYY-MM-DDThh:mm:ssZ format.

Status String Available

The status of the EIP. Valid values:

  • Associating: being associated
  • Unassociating: being disassociated
  • InUse: allocated
  • Available: available
  • Releasing: being released
ReservationOrderType String RENEWCHANGE

The type of the renewal order. Valid values:

  • RENEWCHANGE: renewal with an upgrade or a downgrade
  • TEMP_UPGRADE: temporary upgrade
  • UPGRADE: upgrade
AllocationTime String 2021-04-23T01:37:38Z

The time when the EIP was created. The time is displayed in YYYY-MM-DDThh:mm:ssZ format.

Netmode String public

The network type. The value is set to public, which indicates the Internet.

ChargeType String PostPaid

The billing method of the EIP. Valid values:

  • PostPaid: pay-as-you-go
  • PrePaid: subscription
Description String abc

The description of the EIP.

SegmentInstanceId String eipsg-t4nr90yik5oy38xd****

The IDs of contiguous EIPs.

This value is returned only when you query contiguous EIP groups.

ReservationInternetChargeType String PayByBandwidth

The metering method that is used after the renewal takes effect. Valid values:

  • PayByBandwidth: pay-by-bandwidth
  • PayByTraffic: pay-by-data-transfer
BandwidthPackageId String cbwp-bp1ego3i4j07ccdvf****

The ID of the EIP bandwidth plan.

IpAddress String 47.75.XX.XX

The IP address of the EIP.

Bandwidth String 5

The maximum bandwidth of the EIP. Unit: Mbit/s.

ReservationBandwidth String 12

The bandwidth after the renewal takes effect. Unit: Mbit/s.

EipBandwidth String 101

The maximum bandwidth of the EIP when it is not associated with an EIP bandwidth plan. Unit: Mbit/s.

Name String EIP-01

The name of the EIP.

InstanceRegionId String cn-hangzhou

The region ID of the associated instance.

DeletionProtection Boolean true

Indicates whether deletion protection is enabled. Valid values:

  • true: enabled
  • false: disabled
InstanceId String i-bp15zckdt37cdvf****

The ID of the associated instance.

SecondLimited Boolean false

Indicates whether level-2 throttling is configured. Valid values:

  • true: yes
  • false: no
InstanceType String EcsInstance

The type of the associated instance. Valid values:

  • EcsInstance: an ECS instance in a VPC
  • SlbInstance: an SLB instance in a VPC
  • Nat: a NAT gateway
  • HaVip: an HAVIP
  • NetworkInterface: a secondary ENI
  • IpAddress: an IP address
HDMonitorStatus String false

Indicates whether fine-grained monitoring is enabled for the EIP. Valid values:

  • false: no
  • true: yes
RegionId String cn-hangzhou

The region ID of the EIP.

BandwidthPackageBandwidth String 50

The maximum bandwidth of the EIP bandwidth plan with which the EIP is associated. Unit: Mbit/s.

ServiceManaged Integer 0

Indicates whether the resource is created by the service account.

  • 0: no
  • 1: yes
ExpiredTime String 2021-05-23T02:00:00Z

The time when the EIP expires. The time is displayed in YYYY-MM-DDThh:mm:ssZ format.

ResourceGroupId String rg-acfmxazcdxs****

The ID of the resource group.

AllocationId String eip-2zeerraiwb7ujcdvf****

The ID of the EIP.

InternetChargeType String PayByBandwidth

The metering method of the EIP. Valid values:

  • PayByBandwidth: pay-by-bandwidth
  • PayByTraffic: pay-by-data-transfer
BusinessStatus String Normal

The service status of the EIP. Valid values:

  • Normal: active
  • FinancialLocked: locked
BandwidthPackageType String CommonBandwidthPackage

The type of the bandwidth. Only CommonBandwidthPackage (EIP Bandwidth Plan) is returned.

HasReservationData String false

Indicates whether renewal data is included.

  • false: no
  • true: yes This parameter returns true only when the IncludeReservationData parameter is set to true and some orders have not taken effect.
ISP String BGP

The line type.

  • BGP: BGP (Multi-ISP). All regions support BGP (Multi-ISP) EIPs.
  • BGP_PRO: BGP (Multi-ISP) Pro lines. Only the following regions support BGP (Multi-ISP) Pro lines: China (Hong Kong), Singapore, Malaysia (Kuala Lumpur), Philippines (Manila), Indonesia (Jakarta), and Thailand (Bangkok).

For more information about BGP (Multi-ISP) and BGP (Multi-ISP) Pro, see EIP line types.

If you are allowed to use single-ISP bandwidth, one of the following values is 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 your services are deployed in China East 1 Finance, BGP_FinanceCloud is returned.

OperationLocks Array of LockReason

The details about the locked EIPs.

LockReason
LockReason String financial

The reason why the EIP is locked. Valid values:

  • financial: The EIP is locked due to overdue payments.
  • security: The EIP is locked for security reasons.
Tags Array of Tag

The tag list of the EIP.

Tag
Key String KeyTest

The tag key of the EIP.

Value String ValueTest

The tag value of the EIP.

SecurityProtectionTypes Array of String AntiDDoS_Enhanced

The edition of Anti-DDoS.

  • If an empty value is returned, it indicates that Anti-DDoS Origin Basic is used.
  • If AntiDDoS_Enhanced is returned, it indicates that Anti-DDoS Pro/Premium is used.
PublicIpAddressPoolId String pippool-2vc0kxcedhquybdsz****

The ID of the IP address pool to which the EIP belongs.

VpcId String vpc-bp15zckdt37pq72zv****

The ID of the VPC that has IPv4 gateways enabled and that is deployed in the same region as the EIP.

When you associate an EIP with an IP address, the system can enable the IP address to access the Internet based on VPC route configurations.

Note This parameter is returned if InstanceType is set to IpAddress. In this case, the EIP is associated with an IP address.
Zone String cn-hangzhou-a

The zone of the EIP.

This parameter is returned only if your account is included in the whitelist.

Examples

Sample requests

http(s)://[Endpoint]/?Action=DescribeEipAddresses
&RegionId=cn-hangzhou
&IncludeReservationData=false
&Status=Available
&EipAddress=47.75.XX.XX
&AllocationId=eip-2zeerraiwb7ujxscd****
&SegmentInstanceId=eipsg-t4nr90yik5oy38xdy****
&ResourceGroupId=rg-acfmxazb4pcdvf****
&PageNumber=10
&PageSize=10
&ISP=BGP
&Filter.1.Key=CreationStartTime
&Filter.2.Key=CreationEndTime
&Filter.1.Value=2023-01-01T01:00Z
&Filter.2.Value=2023-01-06T02:00Z
&LockReason=financial
&AssociatedInstanceType=EcsInstance
&AssociatedInstanceId=i-2zebb08phyccdvf****
&ChargeType=PostPaid
&DryRun=false
&EipName=EIP-01
&SecurityProtectionEnabled=false
&PublicIpAddressPoolId=pippool-2vc0kxcedhquybdsz****
&Common request parameters

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

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

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "PageSize" : 10,
  "RequestId" : "4EC47282-1B74-4534-BD0E-403F3EE64CAF",
  "PageNumber" : 10,
  "TotalCount" : 1,
  "EipAddresses" : [ {
    "ReservationActiveTime" : "2021-05-23T16:00:00Z",
    "Status" : "Available",
    "ReservationOrderType" : "RENEWCHANGE",
    "AllocationTime" : "2021-04-23T01:37:38Z",
    "Netmode" : "public",
    "ChargeType" : "PostPaid",
    "Description" : "abc",
    "SegmentInstanceId" : "eipsg-t4nr90yik5oy38xd****",
    "ReservationInternetChargeType" : "PayByBandwidth",
    "BandwidthPackageId" : "cbwp-bp1ego3i4j07ccdvf****",
    "IpAddress" : "47.75.XX.XX",
    "Bandwidth" : "5",
    "ReservationBandwidth" : "12",
    "EipBandwidth" : "101",
    "Name" : "EIP-01",
    "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" : "financial"
    } ],
    "Tags" : [ {
      "Key" : "KeyTest",
      "Value" : "ValueTest"
    } ],
    "SecurityProtectionTypes" : [ "AntiDDoS_Enhanced" ],
    "PublicIpAddressPoolId" : "pippool-2vc0kxcedhquybdsz****",
    "VpcId" : "vpc-bp15zckdt37pq72zv****",
    "Zone" : "cn-hangzhou-a"
  } ]
}

Error codes

HttpCode Error code Error message Description
400 InvalidIAssociatedInstanceType.ValueNotSupported The specified value of AssociatedInstanceType is not supported. The error message returned because AssociatedInstanceType is set to an invalid value. Check whether the value is valid.
400 InvalidChargeType.ValueNotSupported The specified ChargeType is not supported. The error message returned because the specified billing method is not supported. Set a supported billing method.
400 InvalidResourceGroupId The specified ResourceGroupId does not exist. The error message returned because the specified resource group ID does not exist.
400 InvalidTagKey The tag keys are not valid. The error message returned because the tag key is invalid.
400 InvalidTagValue The tag values are not valid. The error message returned because the tag value is invalid.
400 OperationUnsupported.ResourceGroupId ResourceGroup is not supported in this region. The error message returned because the resource group feature is disabled.
404 Forbidden.RegionNotFound Specified region is not found during access authentication. The error message returned because the specified region does not exist. Check whether the specified region ID is valid.
404 InvalidLockReason.NotFound The specified LockReason is not found The error message returned because the reason why the EIP is locked is unknown.

For a list of error codes, see Service error codes.