> For the complete documentation index, see [llms.txt](https://docs.console.zenlayer.com/api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.console.zenlayer.com/api-reference/sdn/data-center-port/describeports.md).

# DescribePorts

## 1. API Description

This API (DescribePorts) is used to get Ports

{% hint style="info" %}
**Notes**

* After a port joins a LAG, the `lag` field in the response shows the LAG to which the port belongs. From then on, only the LAG can be used to create services; its member ports can no longer be used individually.
* If `lagIds` is specified, member ports of the specified LAGs are queried, and only ports belonging to these LAGs are returned.
  {% endhint %}

## 2. Input Parameters

The following request parameter list only provides API request parameters.

| Parameter Name  | Required | Type                                                                                     | Description                                                                                                                                                      |
| --------------- | -------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pageSize        | No       | Integer                                                                                  | <p>Number of items per page. Value range: 1-1000.</p><p>Value range: \[1, 1000]</p>                                                                              |
| pageNum         | No       | Integer                                                                                  | <p>Page number, starting from 1.</p><p>Value range: \[1, +)</p><p>Default value: 1</p>                                                                           |
| portIds         | No       | Array of String                                                                          | List of port IDs. Maximum length: 100.                                                                                                                           |
| portName        | No       | String                                                                                   | Port name, up to 255 characters. Supports fuzzy matching, case-insensitive.                                                                                      |
| dcId            | No       | String                                                                                   | Data center four-letter code. Obtainable via the [DescribeDataCenters](https://docs.console.zenlayer.com/api-reference/sdn/location/describedatacenters.md) API. |
| cityName        | No       | String                                                                                   | City name, up to 64 characters. Supports fuzzy matching, case-insensitive.                                                                                       |
| lagIds          | No       | Array of String                                                                          | <p>List of LAG IDs.</p><p>If specified, only member ports of these LAGs are returned. Maximum length: 100.</p>                                                   |
| resourceGroupId | No       | String                                                                                   | <p>Resource group ID.</p><p>If not specified, ports in all resource groups visible to the user are returned.</p>                                                 |
| tagKeys         | No       | Array of String                                                                          | <p>Search by tag keys.</p><p>Up to 20 tag keys.</p>                                                                                                              |
| tags            | No       | Array of [Tag](https://docs.console.zenlayer.com/api-reference/sdn/datastructure.md#tag) | <p>Search by tags.</p><p>Up to 20 tags.</p>                                                                                                                      |

## 3. Output Parameters

| Parameter Name | Type                                                                                               | Description                                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| requestId      | String                                                                                             | <p>The unique request ID, which is returned for each request.</p><p>RequestId is required for locating a problem.</p> |
| totalCount     | Integer                                                                                            | Total number of records matching the criteria.                                                                        |
| dataSet        | Array of [PortInfo](https://docs.console.zenlayer.com/api-reference/sdn/datastructure.md#portinfo) | The result set of the port list.                                                                                      |

## 4. Code Example

{% tabs %}
{% tab title="Example" %}
**1. Query ports by port ID.**

```json
POST /api/v2/sdn HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: DescribePorts
<Common Request Params>

Request: {
  "portIds": ["your-port-id"]
}

Response: {
    "requestId": "TEEFDCA5B-76FB-4E91-A18E-DF7F5D2CE41F",
    "response": {
        "requestId": "TEEFDCA5B-76FB-4E91-A18E-DF7F5D2CE41F",
        "totalCount": 1,
        "dataSet": [
        {
            "portId":"your-port-id",
            "portName":"your-port-name",
            "portRemarks":"your-port-remark",
            "portType":"1G",
            "dcId":"SIN1",
            "dcName":"AP-Singapore1",
            "cityName":"Singapore",
            "areaName":"Asia Pacific",
            "businessEntityName":"your-business-entity-name",
            "connectionStatus":"ACTIVE",
            "portStatus":"RUNNING",
            "loaStatus":"LOA_NOT_UPLOAD",
            "loaDownloadUrl":"your-loa-download-url",
            "createdTime":"YYYY-MM-ddTHH:mm:ssZ",
            "expiredTime":"YYYY-MM-ddTHH:mm:ssZ",
            "period":12,
            "isCreateBusinessAllowed":true,
            "lag":{
                "lagId":"your-lag-id",
                "lagName":"your-lag-name"
            }
        }]
    }
}
```

**2. Query member ports of a specified LAG.**

```json
POST /api/v2/sdn HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: DescribePorts
<Common Request Params>

Request: {
  "lagIds": ["your-lag-id"]
}

Response: {
    "requestId": "TEEFDCA5B-76FB-4E91-A18E-DF7F5D2CE41F",
    "response": {
        "requestId": "TEEFDCA5B-76FB-4E91-A18E-DF7F5D2CE41F",
        "totalCount": 1,
        "dataSet": [
        {
            "portId":"your-member-port-id",
            "portName":"your-member-port-name",
            "portType":"10G",
            "dcId":"SIN1",
            "dcName":"AP-Singapore1",
            "cityName":"Singapore",
            "areaName":"Asia Pacific",
            "connectionStatus":"ACTIVE",
            "portStatus":"RUNNING",
            "createdTime":"YYYY-MM-ddTHH:mm:ssZ",
            "isCreateBusinessAllowed":false,
            "lag":{
                "lagId":"your-lag-id",
                "lagName":"your-lag-name"
            }
        }]
    }
}
```

{% endtab %}
{% endtabs %}

## 5. Developer Resources

Zenlayer Cloud API 2.0 integrates [SDKs](https://docs.console.zenlayer.com/api-reference/api-introduction/toolkit/api-sdk.md)，to make it easier for you to call APIs. More programming languages will be supported.

## 6. Error Codes

The following only lists the error codes related to the API business logic. For other error codes, see [Common Error Codes](https://docs.console.zenlayer.com/api-reference/api-introduction/instruction/commonerrorcode.md).

| HTTP Status Code | Error Code | Description |
| ---------------- | ---------- | ----------- |
