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

Usage notes

You can call this operation to query information about EIPs in a specified region, including 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 true

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
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 IP addresses with commas (,).

Note If you set both the EipAddress and AllocationId parameters, 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 IDs with commas (,).

Note If you set both the EipAddress and AllocationId parameters, 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 ID of the contiguous EIP group.

ResourceGroupId String No rg-acfmxazb4pcdvf****

The ID of the resource group to which the EIP belongs.

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: BGP (Multi-ISP).

    Up to 89 high-quality BGP lines are available worldwide. Direct connections with multiple Internet service providers (ISPs), including China Telecom, China Unicom, China Mobile, China Mobile Tietong, China Netcom, CERNET, China Broadcast Network, Dr. Peng Group, and Founder, can be established in all regions in the Chinese mainland.

  • BGP_PRO: BGP (Multi-ISP) Pro.

    BGP (Multi-ISP) Pro lines optimize data transmission to the Chinese mainland and improve connection quality for international services. Compared with BGP (Multi-ISP), when BGP (Multi-ISP) Pro lines provide services to users in the Chinese mainland (excluding data centers), cross-border connections are established by using ISP services in the Chinese mainland. This reduces network latency.

BGP (Multi-ISP) lines are supported in all regions. BGP (Multi-ISP) Pro lines are supported only in the China (Hong Kong) region.

Note If your account is included in the BGP (single ISP) whitelist, you can set the ISP parameter to ChinaTelecom, ChinaUnicom, or ChinaMobile. If your workloads are deployed in China East 1 Finance, this parameter is required and you must set the value to BGP_FinanceCloud.
Filter.1.Key String No CreationStartTime

The filter key used to query resources. Set the value to CreationStartTime, which is 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 is the time when the system completed creating the resource.

Filter.1.Value String No 2021-05-22T09:12:00Z

The filter value used to query resources. Specify the time in YYYY-MM-DDThh:mm:ssZ format. The time must be in UTC.

Filter.2.Value String No 2021-05-22T09:15:00Z

The filter value used to query resources. Specify the time in YYYY-MM-DDThh:mm:ssZ 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 elastic network interface (ENI)
    Note You can associate only one EIP with each ECS instance, SLB instance, or HAVIP. 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.

Set the value to PostPaid (pay-as-you-go).

DryRun Boolean No false

Specifies whether to only check the request without performing the operation. Valid values:

  • true: checks the request without querying EIPs. The system checks the required parameters, request syntax, and limits. If the request fails the check, an error message is returned. If the request passes the check, the DryRunOperation error code is returned.
  • false (default): sends the API request. If the request passes the check, 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): disables Anti-DDoS Pro/Premium.
  • true: enables Anti-DDoS Pro/Premium.

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 number of the returned page.

TotalCount Integer 10

The number of entries returned.

EipAddresses Array of EipAddress

The details about the EIPs.

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: Valid values:

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

The type of the renewal order. Valid values:

  • RENEWCHANGE: renewal with upgrade or 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.

ChargeType String PostPaid

The billing method of the EIP. Valid values:

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

The description of the EIP.

SegmentInstanceId String eipsg-t4nr90yik5oy38xd****

The ID of the contiguous EIP group.

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 maximum 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
HDMonitorStatus String false

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

  • false: disabled
  • true: enabled
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 EIP is created by the service account. Valid values:

  • 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: Valid values:

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

The status of the EIP. Valid values:

  • Normal: normal
  • 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.

This parameter returns true only when the IncludeReservationData parameter is set to true and some orders have not taken effect.

ISP String BGP

The ISP.

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.
AvailableRegions Array of String cn-hangzhou

The region ID of the EIP.

SecurityProtectionTypes Array of String AntiDDoS_Enhanced

The edition of Anti-DDoS.

  • If this parameter is empty, it indicates that Anti-DDoS Origin is used.
  • If AntiDDoS_Enhanced is returned, it indicates that Anti-DDoS Pro/Premium is used.

Examples

Sample requests

http(s)://[Endpoint]/?Action=DescribeEipAddresses
&RegionId=cn-hangzhou
&IncludeReservationData=true
&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=2021-05-22T09:12:00Z
&Filter.2.Value=2021-05-22T09:15:00Z
&LockReason=financial
&AssociatedInstanceType=EcsInstance
&AssociatedInstanceId=i-2zebb08phyccdvf****
&ChargeType=PostPaid
&DryRun=false
&EipName=EIP-01
&SecurityProtectionEnabled=false
&<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>10</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>
        <AvailableRegions>cn-hangzhou</AvailableRegions>
        <SecurityProtectionTypes>AntiDDoS_Enhanced</SecurityProtectionTypes>
    </EipAddresses>
</DescribeEipAddressesResponse>

JSON format 

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

{
  "PageSize" : 10,
  "RequestId" : "4EC47282-1B74-4534-BD0E-403F3EE64CAF",
  "PageNumber" : 10,
  "TotalCount" : 10,
  "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"
    } ],
    "AvailableRegions" : [ "cn-hangzhou" ],
    "SecurityProtectionTypes" : [ "AntiDDoS_Enhanced" ]
  } ]
}

Error codes

HttpCode Error codes 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 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, visit the API Error Center.