GoDaddy
Support
API ReferenceDomainDomain LifecycleDomains & DNSv3 (Recommended)Domains

Domains

View as Markdown

The core domain entity collection. Supports listing and reading owned domain records, and cancelling registrations.

List registered domains

GET
/domain-names

Authorization

bearerAuth
AuthorizationBearer <token>

Personal Access Token (PAT). Generate one from the developer dashboard. Pass as: Authorization: Bearer <token>.

In: header

Query Parameters

pageToken?string

Opaque cursor from the links[rel=next or rel=prev] href of the previous page. When present, the response begins immediately after the item that produced the token. Omit to start from the beginning of the collection.

pageTokenDirection?string

Optional token direction when pageToken is set; ignored otherwise.

Value in

  • "backward"
  • "forward"
pageSize?integer

Maximum number of domains in the response. Defaults to 100 when omitted. Offset-based "page" parameter is not supported, only cursor-based "pageToken".

Range1 <= value <= 200
Default100
statuses?array<>

Filter results to domains with one or more lifecycle statuses. Supply multiple values as a single comma-separated list, e.g. ?statuses=ACTIVE,EXPIRED. Multiple values are combined with logical OR — returns domains matching ANY of the specified statuses. See DomainStatus for accepted values (ACTIVE, EXPIRED, PENDING_REGISTRATION, etc.). Cannot be combined with the lifecycleGroups parameter. Use this for precise filtering on specific known status values; for coarse lifecycle phases, consider lifecycleGroups.

Itemsitems <= 50
lifecycleGroups?array<>

Filter results to domains belonging to one or more status groups. Supply multiple values as a single comma-separated list, e.g. ?lifecycleGroups=REGISTERED,PENDING. Multiple values are combined with logical OR. Cannot be combined with the statuses parameter. Use this for coarse lifecycle phases that remain stable as new statuses are added; for precise filtering, use statuses.

updatedAfter?string

Return only domains last updated after this timestamp (exclusive). Must be a valid RFC 3339 date-time.

Formatdate-time
expiresBefore?string

Return only domains whose registration expires before this timestamp (exclusive). Must be a valid RFC 3339 date-time.

Formatdate-time

Header Parameters

X-Request-Id?string

Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/domain-names?pageToken=eyJkb21haW4iOiJleGFtcGxlLmNvbSJ9&statuses=ACTIVE%2CEXPIRED&lifecycleGroups=REGISTERED%2CPENDING&updatedAfter=2026-01-01T00%3A00%3A00Z&expiresBefore=2027-01-01T00%3A00%3A00Z"
{  "items": [    {      "domain": "example.com",      "status": "ACTIVE",      "expiresAt": "2027-06-12T10:02:10Z",      "createdAt": "2026-06-12T10:02:10Z",      "autoRenew": true,      "privacy": false,      "transferLock": true,      "nameServers": [        "ns01.domaincontrol.com",        "ns02.domaincontrol.com"      ],      "links": [        {          "rel": "self",          "href": "/v3/domains/domain-names/example.com"        }      ]    },    {      "domain": "mysite.net",      "status": "ACTIVE",      "expiresAt": "2027-08-01T00:00:00Z",      "createdAt": "2025-08-01T00:00:00Z",      "autoRenew": false,      "privacy": true,      "transferLock": true,      "nameServers": [        "ns01.domaincontrol.com",        "ns02.domaincontrol.com"      ],      "links": [        {          "rel": "self",          "href": "/v3/domains/domain-names/mysite.net"        }      ]    }  ],  "links": [    {      "rel": "self",      "href": "/v3/domains/domain-names?statuses=ACTIVE&pageSize=25"    },    {      "rel": "next",      "href": "/v3/domains/domain-names?statuses=ACTIVE&pageSize=25&pageToken=eyJkb21haW4iOiJteXNpdGUubmV0In0"    }  ]}

Get a registered domain

GET
/domain-names/{domain-name}

Authorization

bearerAuth
AuthorizationBearer <token>

Personal Access Token (PAT). Generate one from the developer dashboard. Pass as: Authorization: Bearer <token>.

In: header

Path Parameters

domain-name*string

The domain name in punycode A-label form (e.g., example.com). For IDNs, use the punycode representation.

Header Parameters

X-Request-Id?string

Optional client-generated request correlation identifier, propagated across services and returned in the response X-Request-Id header.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/domain-names/example.com"
{  "domain": "string",  "idnDomain": "string",  "status": "ACTIVE",  "expiresAt": "string",  "createdAt": "string",  "renewBy": "string",  "updatedAt": "string",  "autoRenew": true,  "privacy": true,  "transferLock": true,  "nameServers": [],  "links": [    {      "href": "http://example.com",      "rel": "string",      "title": "string",      "targetMediaType": "string",      "targetSchema": null,      "method": "string",      "submissionMediaType": "application/json",      "submissionSchema": null    }  ]}

Agent & Automation Notes

Scopesdomains.domain:read, domains.domain:create, domains.dns:update, domains.nameserver:update
Rate limit60 req/min per credential
On failureGET operations are safe to retry. POST registrations use Idempotency-Key. Poll async operations — do not resubmit.

Related

Last updated on

How is this guide?