tencent cloud

DescribeAddresses
Download PDF
Last updated:2025-12-22 16:36:57
DescribeAddresses
Last updated: 2025-12-22 16:36:57
Download PDF

1. API Description

Domain name for API request: vpc.intl.tencentcloudapi.com.

This API (DescribeAddresses) is used to query the information of one or multiple Elastic IPs.

  • If the parameter is empty, a number (as specified by the Limit, the default value is 20) of EIPs will be returned.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: DescribeAddresses.
Version Yes String Common Params. The value used for this API: 2017-03-12.
Region Yes String Common Params. For more information, please see the list of regions supported by the product. This API only supports: ap-bangkok, ap-beijing, ap-chengdu, ap-chongqing, ap-guangzhou, ap-hongkong, ap-jakarta, ap-nanjing, ap-seoul, ap-shanghai, ap-shanghai-fsi, ap-shenzhen-fsi, ap-singapore, ap-tokyo, eu-frankfurt, na-ashburn, na-siliconvalley, sa-saopaulo.
AddressIds.N No Array of String List of unique IDs for identifying Elastic IP (EIP). The EIP unique ID is in the format of eip-11112222. You can use the DescribeAddresses API to obtain the AddressId. The parameters AddressIds and Filters.address-id cannot be specified simultaneously.
Filters.N No Array of Filter The maximum number of Filters per request is 10, and the maximum number of Filter.Values per request is 100. The detailed filter conditions are as follows:
  • address-id - String - Optional - Filter by the unique id of the EIP. the unique id of EIP is in the format of EIP-11112222. you can obtain the address-id through the DescribeAddresses API.
  • address-name - String - Optional - Filter by the EIP name. fuzzy filtering is not supported. available for use through the DescribeAddresses API to obtain the address-name. note: when specifying the address-name parameter, only the first passed in address-name parameter is supported for query execution.
  • address-ip - String - Optional - Filter by the ip address of the EIP. you can obtain address-ip through the DescribeAddresses API.
  • address-status - String - Optional - Filter by the EIP status. valid values: CREATING, BINDING, BIND, UNBINDING, UNBIND, OFFLINING, and BIND_ENI.
  • instance-id - String - Optional - Filter by instance id bound to EIP. instance id is in the format of ins-11112222. you can obtain instance-id through the DescribeAddresses API.
  • private-ip-address - String - Optional - Filter by the private ip bound to the EIP. you can obtain private-ip-address through the DescribeAddresses API. note: when specifying the private-ip-address parameter, only the first passed-in private-ip-address parameter is supported for query execution.
  • network-interface-id - String - Optional - Filter by the id of the ENI bound to the EIP. the ENI id is in the format such as eni-11112222. you can obtain the network-interface-id through the DescribeAddresses API.
  • is-arrears - String - Optional - Filters by whether the EIP is overdue. (TRUE: EIP is overdue | FALSE: EIP is in normal fee state).
  • instance-type - String - Optional - Filters by the instance type bound to the EIP. valid values: CVM, NAT, ENI, CLB, HAVIP, DHCPIP, EKS, VPCE, and WAF.
    Note: when using only the instance-type filter condition, the system returns by default the list of bound resources for all EIP types (including EIP, AnycastEIP, HighQualityEIP, AntiDDoSEIP, and ResidentialEIP). to query bound resources for a specific EIP type or WanIP, specify both the instance-type and address-type parameters to configure.
  • address-type - String - Optional - Filter by IP type. valid values: WanIP, EIP, AnycastEIP, HighQualityEIP, AntiDDoSEIP, and ResidentialEIP. default value is EIP.
  • address-isp - String - Optional - Filter by ISP type. valid values: BGP, CMCC, CUCC, and CTCC.
  • dedicated-cluster-id - String - Optional - Filter by unique CDC ID, such as cluster-11112222.
  • tag-key - String - Optional - Filter by tag key.
  • tag-value - String - Optional - Filter by tag value.
  • tag:tag-key - String - Optional - Filter by tag key-value pair. Use a specific tag key to replace tag-key.
    		•
    Offset No Integer The Offset. The default value is 0. For more information on Offset, see the relevant section in the API Introduction.
    Limit No Integer Number of returned results. Default value: 20. Maximum value: 100. For more information on Limit, see the relevant section in the API Introduction.

    3. Output Parameters

    Parameter Name Type Description
    TotalCount Integer Number of EIPs meeting the condition.
    AddressSet Array of Address List of EIPs details.
    RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

    4. Example

    Example1 Querying EIP Information

    This example shows you how to query EIP information.

    Input Example

    POST / HTTP/1.1
Host: vpc.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeAddresses
<Common request parameters>

{}

    Output Example

    {
    "Response": {
        "TotalCount": 2,
        "AddressSet": [
            {
                "AddressId": "eip-qhx8udkc",
                "AddressName": "Not named",
                "AddressIp": "1.14.91.34",
                "AddressStatus": "UNBIND",
                "AddressType": "EIP",
                "InstanceId": "ins-wf123456",
                "InstanceType": null,
                "NetworkInterfaceId": "eni-12345678",
                "PrivateAddressIp": "10.2.3.4",
                "IsArrears": false,
                "IsBlocked": false,
                "IsEipDirectConnection": false,
                "EipAlgType": {
                    "Ftp": true,
                    "Sip": true
                },
                "LocalBgp": false,
                "CascadeRelease": false,
                "CreatedTime": "2022-08-11T03:57:05Z",
                "TagSet": [],
                "InternetChargeType": "TRAFFIC_POSTPAID_BY_HOUR",
                "Bandwidth": 1,
                "DeadlineDate": null,
                "Egress": "center_egress1",
                "InternetServiceProvider": "BGP"
            },
            {
                "AddressId": "eip-qygpzm9y",
                "AddressName": "Not named",
                "AddressIp": "1.14.90.212",
                "AddressStatus": "UNBIND",
                "AddressType": "EIP",
                "InstanceId": "ins-12345678",
                "InstanceType": null,
                "NetworkInterfaceId": "eni-12345678",
                "PrivateAddressIp": "10.3.4.5.6",
                "IsArrears": false,
                "IsBlocked": false,
                "IsEipDirectConnection": false,
                "Egress": "center_egress1",
                "EipAlgType": {
                    "Ftp": true,
                    "Sip": true
                },
                "LocalBgp": false,
                "CascadeRelease": false,
                "CreatedTime": "2022-08-11T03:47:03Z",
                "TagSet": [],
                "InternetChargeType": "TRAFFIC_POSTPAID_BY_HOUR",
                "Bandwidth": 1,
                "DeadlineDate": null,
                "InternetServiceProvider": "BGP"
            }
        ],
        "RequestId": "4ead34c4-3112-40fe-bbde-2295eee9d664"
    }
}

    Example2 Querying a Public IP

    This example shows you how to query a public IP.

    Input Example

    https://vpc.intl.tencentcloudapi.com/?Action=DescribeAddresses
&Filters.0.Name=address-type
&Filters.0.Values.0=WanIP
&<Common request parameters>

    Output Example

    {
    "Response": {
        "TotalCount": 1,
        "AddressSet": [
            {
                "AddressId": "eip-93gyo275",
                "AddressName": "gwlb",
                "AddressIp": "122.51.235.39",
                "AddressStatus": "BIND",
                "AddressType": "WanIP",
                "InstanceId": "ins-b2mc0ko1",
                "InstanceType": "CVM",
                "NetworkInterfaceId": "eni-akohvkv6",
                "PrivateAddressIp": "10.0.1.9",
                "IsArrears": false,
                "IsBlocked": false,
                "IsEipDirectConnection": false,
                "EipAlgType": {
                    "Ftp": true,
                    "Sip": true
                },
                "LocalBgp": false,
                "CascadeRelease": false,
                "Egress": "center_egress1",
                "CreatedTime": "2024-11-11T07:42:49Z",
                "TagSet": [
                    {
                        "Key": "qcs:tag:createdBy",
                        "Value": "Root:100002840660"
                    }
                ],
                "BandwidthPackageId": null,
                "InternetChargeType": "TRAFFIC_POSTPAID_BY_HOUR",
                "Bandwidth": 5,
                "DeadlineDate": null,
                "InternetServiceProvider": "BGP"
            }
        ],
        "RequestId": "f9b58176-c138-45ba-a0e2-7a55117e2833"
    }
}

    Example3 Querying Elastic IP

    This example shows you how to query Elastic IPs.

    Input Example

    https://vpc.intl.tencentcloudapi.com/?Action=DescribeAddresses
&AddressIds.0=eip-12345678
&<Common request parameters>

    Output Example

    {
    "Response": {
        "TotalCount": 0,
        "AddressSet": [
            {
                "AddressId": "eip-12345678",
                "AddressName": "demo",
                "AddressStatus": "UNBIND",
                "AddressIp": "34.3.4.5.6",
                "InstanceId": "ins-12345678",
                "CreatedTime": "2020-09-22T00:00:00+00:00",
                "NetworkInterfaceId": "eni-12345678",
                "PrivateAddressIp": "10.2.3.4",
                "IsArrears": true,
                "IsBlocked": true,
                "IsEipDirectConnection": true,
                "AddressType": "WanIp",
                "CascadeRelease": true,
                "EipAlgType": {
                    "Ftp": true,
                    "Sip": true
                },
                "InternetServiceProvider": "BGP",
                "LocalBgp": true,
                "Bandwidth": 1,
                "InternetChargeType": "TRAFFIC_POSTPAID_BY_HOUR",
                "TagSet": [
                    {
                        "Key": "name",
                        "Value": "Sam"
                    }
                ],
                "DeadlineDate": "2020-09-22",
                "InstanceType": "CVM",
                "Egress": "CENTER_EGRESS_1"
            }
        ],
        "RequestId": "95eb79b9-2e72-45b1-a1ac-03138778521a"
    }
}

    5. Developer Resources

    SDK

    TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

    Command Line Interface

    6. Error Code

    The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

    Error Code Description
    InvalidParameter A parameter error occurred.
    InvalidParameter.InvalidFilter The filter rule is invalid.
    InvalidParameterValue.AddressIdMalformed This IP address ID is invalid.
    InvalidParameterValue.InvalidDedicatedClusterId Invalid DedicatedClusterId.
    InvalidParameterValue.LimitExceeded The parameter value exceeds the limit.
    InvalidParameterValue.NetworkInterfaceIdMalformed Incorrect network interface ID.
    InvalidParameterValue.ResourceIdMalformed The resource ID is incorrect.
    LimitExceeded.NumberOfFilters Exceeded the character limit of a filter name.
    UnsupportedOperation Unsupported operation.
    Was this page helpful?
    You can also Contact Sales or Submit a Ticket for help.
    Yes
    No

    Feedback