• Domain Name Service

dns
  1. Help Center
  2. Domain Name Service
  3. API Reference
  4. API Description
  5. Record Set Management
  6. Querying All Record Sets

Querying All Record Sets

Function

Query record sets in list.

URI

GET /v2/recordsets?zone_type={zone_type}&limit={limit}&marker={marker}&offset={offset}&tags={tags}&status={status}&type={type}&name={name}&id={id}&records={records}&sort_key={sort_key}&sort_dir={sort_dir}

For details, see Table 1.
Table 1 Parameters in the URI

Parameter

Mandatory

Type

Description

zone_type

No

string

Zone type of the record set to be queried, which can be public or private

  • public: Record sets in public zones are queried.
  • private: Record sets in private zones are queried.

    If the value is left blank, record sets in public zones are queried by default.

marker

No

string

Start resource ID of pagination query

If the parameter is left blank, only resources on the first page are queried.

limit

No

string

  • Number of resources returned on each page
  • Value range: 0–500

    Commonly used values are 10, 20, and 50.

offset

No

int

  • Start page of the list, which ranges from 0 to 2147483647.
  • When the value of marker is not blank, it determines the start of a page.

tags

No

string

Resource tag

The format is as follows: key1,value1|key2,value2.

Multiple tags are separated by vertical bar (|). The key and value of each tag are separated by comma (,).

All tags listed will be queried.

For details, see section Adding Resource Tags.

status

No

string

Status of the record sets to be queried

The value can be ACTIVE, ERROR, DISABLE, FREEZE, PENDING_CREATE, PENDING_UPDATE, or PENDING_DELETE

  • If this parameter is left blank, all record sets will be queried.
  • If the value is ACTIVE, record sets in normal state will be queried.
  • If the value is ERROR, record sets in failed state will be queried.
  • If the value is DISABLE, record sets in disabled state will be queried.
  • If the value is FREEZE, record sets in frozen state will be queried.
  • If the value is PENDING_CREATE, record sets in creating state will be queried.
  • If the value is PENDING_UPDATE, record sets in updating state will be queried.
  • If the value is PENDING_DELETE, record sets in deleting state will be queried.

type

No

string

Type of the record sets to be queried

The value can be A, CNAME, MX, AAAA, TXT, SRV, NS, or CAA.

  • If this parameter is left blank, all types of record sets will be queried.
  • If the value is A, all A record sets will be queried.
  • If the value is CNAME, all CNAME record sets will be queried.
  • If the value is MX, all MX record sets will be queried.
  • If the value is AAAA, all AAAA record sets will be queried.
  • If the value is TXT, all TXT record sets will be queried.
  • If the value is SRV, all SRV record sets will be queried.
  • If the value is NS, all NS record sets will be queried.
  • If the value is CAA, all CAA record sets will be queried.

name

No

string

Name included in the names of record sets to be queried

id

No

string

ID included in the IDs of record sets to be queried

records

No

string

Value included in the values of record sets to be queried

sort_key

No

string

Sorting condition of the record set list

The value can be:

  • name: domain name
  • type: record set type

sort_dir

No

string

Sorting order of the record set list

The value can be:

  • desc: descending order
  • asc: ascending order

Request

None

Response

  • Parameter description
    Table 2 Parameters in the response

    Parameter

    Type

    Description

    recordsets

    List data structure

    Record set list object

    metadata

    object

    Number of resources that meet the filter condition

    Table 2 describes parameters under the recordsets field, and Table 4 describes the parameter under the metadata field.
    Table 3 Description of the recordsets field

    Parameter

    Type

    Description

    id

    string

    Record set ID

    name

    string

    Record set name

    description

    string

    Record set description

    zone_id

    string

    Zone ID of the record set

    zone_name

    string

    Zone name of the record set

    type

    string

    Record set type

    The value can be A, AAAA, MX, CNAME, TXT, NS (only in public zones), SRV, PTR (only in private zones), and CAA (only in public zones).

    ttl

    int

    Caching period of a domain name (in seconds)

    A longer caching period makes a change on the authoritative DNS server take longer time to be synchronized to other DNS servers.

    records

    List<string>

    Domain name resolution result

    create_at

    string

    Time when the record set was created

    update_at

    string

    Time when the record set was updated

    status

    enum

    Resource status

    The value can be PENDING_CREATE, ACTIVE, PENDING_UPDATE, PENDING_DELETE, or ERROR.

    default

    boolean

    Whether the record set is created by default

    A default record set cannot be deleted.

    project_id

    string

    Project ID of the record set

    links

    object

    Link of the current resource or other related resources

    When a response is broken into pages, a next link is provided to retrieve all results.

    Table 4 Description of the metadata field

    Parameter

    Type

    Description

    total_count

    int

    Total number of resources

  • Example response
    {
        "links": {
            "self": "https://Endpoint/v2/recordsets"
        },
        "recordsets": [
            {
                "id": "2c9eb155587194ec01587224c9f9014a",
                "name": "example.com.",
                "type": "SOA",
                "ttl": 300,
                "records": [
                    "ns1.hotrot.de. xx.example.com. (1 7200 900 1209600 300)"
                ],
                "status": "ACTIVE",
                "links": {
                    "self": "https://Endpoint/v2/zones/2c9eb155587194ec01587224c9f90149/recordsets/2c9eb155587194ec01587224c9f9014a"
                },
                "zone_id": "2c9eb155587194ec01587224c9f90149",
                "zone_name": "example.com.",
                "create_at": "2016-11-17T11:56:03.439",
                "update_at": "2016-11-17T11:56:03.827",
                "default": true,
                "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c"
            },
            {
                "id": "2c9eb155587194ec01587224c9f9014c",
                "name": "example.com.",
                "type": "NS",
                "ttl": 172800,
                "records": [
                    "ns2.hotrot.de.",
                    "ns1.hotrot.de."
                ],
                "status": "ACTIVE",
                "links": {
                    "self": "https://Endpoint/v2/zones/2c9eb155587194ec01587224c9f90149/recordsets/2c9eb155587194ec01587224c9f9014c"
                },
                "zone_id": "2c9eb155587194ec01587224c9f90149",
                "zone_name": "example.com.",
                "create_at": "2016-11-17T11:56:03.439",
                "update_at": "2016-11-17T11:56:03.827",
                "default": true,
                "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c"
            },
            {
                "id": "2c9eb155587228570158722996ca0002",
                "name": "example.org.",
                "type": "SOA",
                "ttl": 300,
                "records": [
                    "ns1.hotrot.de. xx.example.org. (1 7200 900 1209600 300)"
                ],
                "status": "ACTIVE",
                "links": {
                    "self": "https://Endpoint/v2/zones/2c9eb155587228570158722996c50001/recordsets/2c9eb155587228570158722996ca0002"
                },
                "zone_id": "2c9eb155587228570158722996c50001",
                "zone_name": "example.org.",
                "create_at": "2016-11-17T12:01:17.996",
                "update_at": "2016-11-17T12:56:03.827",
                "default": true,
                "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c"
            },
            {
                "id": "2c9eb155587228570158722996ca0004",
                "name": "example.org.",
                "type": "NS",
                "ttl": 172800,
                "records": [
                    "ns2.hotrot.de.",
                    "ns1.hotrot.de."
                ],
                "status": "ACTIVE",
                "links": {
                    "self": "https://Endpoint/v2/zones/2c9eb155587228570158722996c50001/recordsets/2c9eb155587228570158722996ca0004"
                },
                "zone_id": "2c9eb155587228570158722996c50001",
                "zone_name": "example.org.",
                "create_at": "2016-11-17T12:01:17.996",
                "update_at": "2016-11-17T12:56:03.827",
                "default": true,
                "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c"
            },
            {
                "id": "2c9eb155587228570158722b6ac30007",
                "name": "www.example.com.",
                "description": "This is an example record set.",
                "type": "A",
                "ttl": 300,
                "records": [
                    "192.168.10.2",
                    "192.168.10.1"
                ],
                "status": "ACTIVE",
                "links": {
                    "self": "https://Endpoint/v2/zones/2c9eb155587194ec01587224c9f90149/recordsets/2c9eb155587228570158722b6ac30007"
                },
                "zone_id": "2c9eb155587194ec01587224c9f90149",
                "zone_name": "example.com.",
                "create_at": "2016-11-17T12:03:17.827",
                "update_at": "2016-11-17T12:56:03.827",
                "default": false,
                "project_id": "e55c6f3dc4e34c9f86353b664ae0e70c"
            }
        ],
        "metadata": {
            "total_count": 5
        }
    }
    

Returned Value

See General Request Return Code.