API Reference

DNS

Records

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List DNS Records

GET/zones/{zone_id}/dns_records

List, search, sort, and filter a zones' DNS records.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

DNS ReadDNS Write

Path ParametersExpand Collapse

zone_id: string

Identifier.

maxLength32

Query ParametersExpand Collapse

comment: optional object { absent, contains, endswith, 3 more }

absent: optional string

If this parameter is present, only records without a comment are returned.

contains: optional string

Substring of the DNS record comment. Comment filters are case-insensitive.

endswith: optional string

Suffix of the DNS record comment. Comment filters are case-insensitive.

exact: optional string

Exact value of the DNS record comment. Comment filters are case-insensitive.

present: optional string

If this parameter is present, only records with a comment are returned.

startswith: optional string

Prefix of the DNS record comment. Comment filters are case-insensitive.

content: optional object { contains, endswith, exact, startswith }

contains: optional string

Substring of the DNS record content. Content filters are case-insensitive.

endswith: optional string

Suffix of the DNS record content. Content filters are case-insensitive.

exact: optional string

Exact value of the DNS record content. Content filters are case-insensitive.

startswith: optional string

Prefix of the DNS record content. Content filters are case-insensitive.

direction: optional SortDirection

Direction to order DNS records in.

One of the following:

"asc"

"desc"

match: optional "any" or "all"

Whether to match all search requirements or at least one (any). If set to all, acts like a logical AND between filters. If set to any, acts like a logical OR instead. Note that the interaction between tag filters is controlled by the tag-match parameter instead.

One of the following:

"any"

"all"

name: optional object { contains, endswith, exact, startswith }

contains: optional string

Substring of the DNS record name. Name filters are case-insensitive.

endswith: optional string

Suffix of the DNS record name. Name filters are case-insensitive.

exact: optional string

Exact value of the DNS record name. Name filters are case-insensitive.

startswith: optional string

Prefix of the DNS record name. Name filters are case-insensitive.

order: optional "type" or "name" or "content" or 2 more

Field to order DNS records by.

One of the following:

"type"

"name"

"content"

"ttl"

"proxied"

page: optional number

Page number of paginated results.

minimum1

per_page: optional number

Number of DNS records per page.

maximum5000000

minimum1

proxied: optional boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

search: optional string

Allows searching in multiple properties of a DNS record simultaneously. This parameter is intended for human users, not automation. Its exact behavior is intentionally left unspecified and is subject to change in the future. This parameter works independently of the match setting. For automated searches, please use the other available parameters.

tag: optional object { absent, contains, endswith, 3 more }

absent: optional string

Name of a tag which must not be present on the DNS record. Tag filters are case-insensitive.

contains: optional string

A tag and value, of the form <tag-name>:<tag-value>. The API will only return DNS records that have a tag named <tag-name> whose value contains <tag-value>. Tag filters are case-insensitive.

endswith: optional string

A tag and value, of the form <tag-name>:<tag-value>. The API will only return DNS records that have a tag named <tag-name> whose value ends with <tag-value>. Tag filters are case-insensitive.

exact: optional string

A tag and value, of the form <tag-name>:<tag-value>. The API will only return DNS records that have a tag named <tag-name> whose value is <tag-value>. Tag filters are case-insensitive.

present: optional string

Name of a tag which must be present on the DNS record. Tag filters are case-insensitive.

startswith: optional string

A tag and value, of the form <tag-name>:<tag-value>. The API will only return DNS records that have a tag named <tag-name> whose value starts with <tag-value>. Tag filters are case-insensitive.

tag_match: optional "any" or "all"

Whether to match all tag search requirements or at least one (any). If set to all, acts like a logical AND between tag filters. If set to any, acts like a logical OR instead. Note that the regular match parameter is still used to combine the resulting condition with other filters that aren't related to tags.

One of the following:

"any"

"all"

type: optional "A" or "AAAA" or "CAA" or 18 more

Record type.

One of the following:

"A"

"AAAA"

"CAA"

"CERT"

"CNAME"

"DNSKEY"

"DS"

"HTTPS"

"LOC"

"MX"

"NAPTR"

"NS"

"OPENPGPKEY"

"PTR"

"SMIMEA"

"SRV"

"SSHFP"

"SVCB"

"TLSA"

"TXT"

"URI"

ReturnsExpand Collapse

errors: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of object { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

success: true

Whether the API call was successful.

result: optional array of RecordResponse

One of the following:

A = ARecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

AAAA = AAAARecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

CNAME = CNAMERecord { name, ttl, type, 5 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

MX = MXRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

NS = NSRecord { name, ttl, type, 5 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

Openpgpkey = object { id, comment, content, 12 more }

id: string

Identifier.

maxLength32

comment: string

Comments or notes about the DNS record. This field has no effect on DNS responses.

content: string

A single Base64-encoded OpenPGP Transferable Public Key (RFC 4880 Section 11.1)

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

name: string

Complete DNS record name, including the zone name, in Punycode.

maxLength255

minLength1

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

proxied: boolean

Whether the record is receiving the performance and security benefits of Cloudflare.

settings: object { ipv4_only, ipv6_only }

Settings for the DNS record.

ipv4_only: optional boolean

When enabled, only A records will be generated, and AAAA records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

ipv6_only: optional boolean

When enabled, only AAAA records will be generated, and A records will not be created. This setting is intended for exceptional cases. Note that this option only applies to proxied records and it has no effect on whether Cloudflare communicates with the origin using IPv4 or IPv6.

tags: array of RecordTags

Custom tags for the DNS record. This field has no effect on DNS responses.

ttl: TTL

Time To Live (TTL) of the DNS record in seconds. Setting to 1 means 'automatic'. Value must be between 60 and 86400, with the minimum reduced to 30 for Enterprise zones.

One of the following:

number

1

Time To Live (TTL) of the DNS record in seconds. Setting to 1 means 'automatic'. Value must be between 60 and 86400, with the minimum reduced to 30 for Enterprise zones.

type: "OPENPGPKEY"

Record type.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

PTR = PTRRecord { name, ttl, type, 5 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

TXT = TXTRecord { name, ttl, type, 5 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

CAA = CAARecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

CERT = CERTRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

DNSKEY = DNSKEYRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

DS = DSRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

HTTPS = HTTPSRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

LOC = LOCRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

NAPTR = NAPTRRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

SMIMEA = SMIMEARecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

SRV = SRVRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

SSHFP = SSHFPRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

SVCB = SVCBRecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

TLSA = TLSARecord { name, ttl, type, 6 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

URI = URIRecord { name, ttl, type, 7 more }

id: string

Identifier.

maxLength32

created_on: string

When the record was created.

formatdate-time

meta: unknown

Extra Cloudflare-specific information about the record.

modified_on: string

When the record was last modified.

formatdate-time

proxiable: boolean

Whether the record can be proxied by Cloudflare or not.

comment_modified_on: optional string

When the record comment was last modified. Omitted if there is no comment.

formatdate-time

tags_modified_on: optional string

When the record tags were last modified. Omitted if there are no tags.

formatdate-time

result_info: optional object { count, page, per_page, 2 more }

count: optional number

Total number of results for the requested service.

page: optional number

Current page within paginated list of results.

per_page: optional number

Number of results per page of results.

total_count: optional number

Total results available without any search parameters.

total_pages: optional number

The number of total pages in the entire result set.

List DNS Records

HTTP

HTTP

TypeScript

Python

Go

Terraform

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": [
    {
      "name": "example.com",
      "ttl": 3600,
      "type": "A",
      "comment": "Domain verification record",
      "content": "198.51.100.4",
      "private_routing": true,
      "proxied": true,
      "settings": {
        "ipv4_only": true,
        "ipv6_only": true
      },
      "tags": [
        "owner:dns-team"
      ],
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "meta": {},
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "proxiable": true,
      "comment_modified_on": "2024-01-01T05:20:00.12345Z",
      "tags_modified_on": "2025-01-01T05:20:00.12345Z"
    }
  ],
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000,
    "total_pages": 100
  }
}

Returns Examples

200 example

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": [
    {
      "name": "example.com",
      "ttl": 3600,
      "type": "A",
      "comment": "Domain verification record",
      "content": "198.51.100.4",
      "private_routing": true,
      "proxied": true,
      "settings": {
        "ipv4_only": true,
        "ipv6_only": true
      },
      "tags": [
        "owner:dns-team"
      ],
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "created_on": "2014-01-01T05:20:00.12345Z",
      "meta": {},
      "modified_on": "2014-01-01T05:20:00.12345Z",
      "proxiable": true,
      "comment_modified_on": "2024-01-01T05:20:00.12345Z",
      "tags_modified_on": "2025-01-01T05:20:00.12345Z"
    }
  ],
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000,
    "total_pages": 100
  }
}