Skip to content

Get DNS records

GET /api/v2/dns-zones/{id}

Returns the records in one DNS zone, with a short zone summary. This is the canonical list-records endpoint. GET /api/v2/dns-zones/{id}/records returns the same response. Filter with type and name to read only what you plan to change. Use records[].id to update or delete a record. SPF policies are TXT records whose value starts with v=spf1. An API key limited to certain records sees only those records.

The response example is representative. priority, weight and port appear only on the record types that use them. CDN proxy state is not part of this response. GET /api/v2/domains/{id}/dns returns it. zone.recordCount counts the records in this response. zone.totalRecordCount counts the whole zone. Only the first 200 records are published live. zone.exceedsLiveRecordLimit and zone.warnings tell you when the zone is above that limit. Nameservers are not part of this response. GET /api/v2/domains/{id}/nameservers returns them.

Authentication: An API key with the scope read:dns. About keys and scopes

Request

Path parameters

idstringrequired
The DNS zone ID. From GET /api/v2/dns-zones.

Query parameters

typestring
Return only records of this type, for example MX. SPF policies are TXT records. One of A, AAAA, CNAME, ALIAS, MX, TXT, NS, SRV, CAA, TLSA.
namestring
Return only records with this owner name: @ for the apex, a label such as mail or a full name such as mail.example.com.

Example

GET /api/v2/dns-zones/{id}
curl "https://cloud.hostup.se/api/v2/dns-zones/zone_01hxa3b4c5d6e7f8g9h0j1k2m3" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The zone summary and its records.

Response 200
{
"zone": {
"id": "zone_01hxa3b4c5d6e7f8g9h0j1k2m3",
"name": "example.com",
"status": "active",
"recordCount": 4,
"totalRecordCount": 306,
"liveRecordLimit": 200,
"exceedsLiveRecordLimit": true,
"warnings": [
{
"code": "dns_live_record_limit_exceeded",
"severity": "warning",
"message": "This zone has 306 DNS records. Only the first 200 records can be published live; records beyond that limit may be saved but not resolve."
}
]
},
"records": [
{
"id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m3",
"type": "A",
"name": "example.com",
"value": "192.0.2.10",
"ttl": 3600
},
{
"id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m4",
"type": "MX",
"name": "example.com",
"value": "mail.example.com",
"ttl": 3600,
"priority": 10
},
{
"id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m5",
"type": "TXT",
"name": "_dmarc.example.com",
"value": "v=DMARC1; p=none; rua=mailto:dmarc@example.com",
"ttl": 3600
},
{
"id": "drr_01hxa3b4c5d6e7f8g9h0j1k2m6",
"type": "SRV",
"name": "_sip._tcp.example.com",
"value": "sip.example.com",
"ttl": 3600,
"priority": 10,
"weight": 5,
"port": 5060
}
]
}
Response fields
zoneobject
idstring
The DNS zone ID.
namestring
The zone’s domain name.
statusstring
Zone status. One of active, disabled, pending, error, unknown.
recordCountinteger
Records in this response, after the type and name filters.
totalRecordCountinteger
Records in the whole zone before filters, without SOA and apex NS records.
liveRecordLimitinteger
How many records the zone can publish live.
exceedsLiveRecordLimitboolean
True when totalRecordCount is above liveRecordLimit. Records past the limit may be saved but not resolve.
warningsarray of object
Zone warnings. Present when exceedsLiveRecordLimit is true.
codestring
Warning code. One of dns_live_record_limit_exceeded.
severitystring
Always warning. One of warning.
messagestring
The warning in plain English.
recordsarray of object
The zone’s records, after filters.
idstring
typestring
One of A, AAAA, CNAME, ALIAS, MX, TXT, SRV, CAA, NS, TLSA, SOA.
namestring
The full name, such as _dmarc.example.com. The domain itself is example.com.
valuestring
ttlinteger
priorityinteger or null
Present only on MX and SRV records. null when the DNS server returned no priority.
weightinteger or null
Present only on SRV records. null when the DNS server returned no weight.
portinteger or null
Present only on SRV records. null when the DNS server returned no port.
proxiedboolean
Whether the record goes through the CDN proxy. Present only on A, AAAA and CNAME records when the proxy state is known.
proxyReasonstring
Why the proxy state of this record cannot be changed, ready to show. Present only when there is such a reason.
actionsobject
Action gates for this record. Present only when one applies.
canChangeProxyobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
warningsarray of object
Present only on a create response (POST /api/v2/dns-zones/{id}/records) when the record was added but the records with the same name need a look. Examples: several A records, AAAA records left over, several MX records.
codestring
One of same_name_address_records, same_name_ipv6_records, same_name_mx_records.
severitystring
One of warning.
messagestring
recordsarray of object
The existing records behind the warning. The record you created or changed is the main response.
idstring
typestring
namestring
valuestring
priorityinteger or null

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is dns_zone_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.