Retrieve the domains owned by the authenticated account, with cursor pagination, and fetch full detail for any one domain.

Overview

Retrieve the domains registered to an account using GET /v1/domains, then fetch full detail for any single domain using GET /v2/customers/{customerId}/domains/{domain}. List results are paginated using limit and marker cursor parameters.

Domain listing isn't available in v3 yet. This page uses the v1 endpoint (GET /v1/domains) for account-scoped listing and the v2 endpoint (GET /v2/customers/{customerId}/domains/{domain}) for single-domain detail. Prefer v2 for single-domain detail — v2 domain statuses are more consistent, and v2 gives you access to async operation tracking if you need it.

GET /v1/domains returns the domains owned by the authenticated account, paginated with limit and marker. GET /v1/domains/{domain} returns full detail for a single domain.

This page assumes you have a PAT credential. See Authentication and Quickstart if you don't.

Retrieve registered domains

The response is an array of domain summaries. For pagination semantics and a looping example, see Pagination.

The following procedure retrieves the domains registered to the authenticated account.

Run the following command for your preferred language:

curl -s "https://api.godaddy.com/v1/domains?limit=100" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Accept: application/json"

const pat = process.env.GODADDY_PAT;
const res = await fetch("https://api.godaddy.com/v1/domains?limit=100", {
  headers: {
    Authorization: `Bearer ${pat}`,
    Accept: "application/json",
  },
});
const domains = await res.json();
console.log(domains.map((d) => d.domain));

import os, requests

pat = os.environ["GODADDY_PAT"]
res = requests.get(
    "https://api.godaddy.com/v1/domains",
    params={"limit": 100},
    headers={
        "Authorization": f"Bearer {pat}",
        "Accept": "application/json",
    },
)
res.raise_for_status()
for d in res.json():
    print(d["domain"], d.get("status"))

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type Domain struct {
    Domain string `json:"domain"`
    Status string `json:"status"`
}

func main() {
    pat := os.Getenv("GODADDY_PAT")
    req, _ := http.NewRequest("GET",
        "https://api.godaddy.com/v1/domains?limit=100", nil)
    req.Header.Set("Authorization", "Bearer "+pat)
    req.Header.Set("Accept", "application/json")

    res, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer res.Body.Close()

    var domains []Domain
    json.NewDecoder(res.Body).Decode(&domains)
    for _, d := range domains {
        fmt.Println(d.Domain, d.Status)
    }
}

Filtering

GET /v1/domains accepts these query parameters in addition to limit and marker:

Parameter	Notes
`statuses`	Comma-separated list of domain statuses (e.g. `ACTIVE`, `EXPIRED`, `PENDING_TRANSFER`). Returns only domains in one of the listed statuses.
`statusGroups`	Coarser filter — by status group (e.g. `VISIBLE`, `EXPIRED`).
`includes`	Comma-separated list of expansions to include (e.g. `contacts`). Adds related objects to each item without a follow-up call.
`modifiedDate`	ISO-8601 timestamp. Returns only domains modified at or after this time.

Reference: GET /v1/domains.

Get details for a single domain

The response is a DomainDetail object covering registration metadata, expiration, contacts, nameservers, lock state, privacy state, and auto-renew configuration. For the full schema, see the reference.

The following procedure retrieves details for a single domain.

Run the following command for your preferred language:

curl -s "https://api.godaddy.com/v1/domains/example.com" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Accept: application/json"

const pat = process.env.GODADDY_PAT;
const res = await fetch("https://api.godaddy.com/v1/domains/example.com", {
  headers: {
    Authorization: `Bearer ${pat}`,
    Accept: "application/json",
  },
});
const detail = await res.json();
console.log(detail.domain, detail.status, detail.expires);

import os, requests

pat = os.environ["GODADDY_PAT"]
res = requests.get(
    "https://api.godaddy.com/v1/domains/example.com",
    headers={"Authorization": f"Bearer {pat}", "Accept": "application/json"},
)
res.raise_for_status()
d = res.json()
print(d["domain"], d["status"], d["expires"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    pat := os.Getenv("GODADDY_PAT")
    req, _ := http.NewRequest("GET",
        "https://api.godaddy.com/v1/domains/example.com", nil)
    req.Header.Set("Authorization", "Bearer "+pat)
    req.Header.Set("Accept", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()

    var detail struct {
        Domain  string `json:"domain"`
        Status  string `json:"status"`
        Expires string `json:"expires"`
    }
    json.NewDecoder(res.Body).Decode(&detail)
    fmt.Println(detail.Domain, detail.Status, detail.Expires)
}

Reference: GET /v1/domains/{domain}.

v2 — single domain detail

Use the v2 endpoint for single-domain detail. It returns consistent status values and gives you access to async operation tracking if you need it.

The following procedure retrieves domain details for a specific customer.

Run the following command for your preferred language:

curl -s "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/example.com" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Accept: application/json"

const pat = process.env.GODADDY_PAT;
const customer = process.env.CUSTOMER_ID;
const res = await fetch(
  `https://api.godaddy.com/v2/customers/${customer}/domains/example.com`,
  {
    headers: {
      Authorization: `Bearer ${pat}`,
      Accept: "application/json",
    },
  },
);
const detail = await res.json();
console.log(detail.domain, detail.status);

import os, requests

customer = os.environ["CUSTOMER_ID"]
res = requests.get(
    f"https://api.godaddy.com/v2/customers/{customer}/domains/example.com",
    headers={
        "Authorization": f"Bearer {os.environ['GODADDY_PAT']}",
        "Accept": "application/json",
    },
)
res.raise_for_status()
d = res.json()
print(d["domain"], d["status"])

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    customer := os.Getenv("CUSTOMER_ID")
    pat := os.Getenv("GODADDY_PAT")
    req, _ := http.NewRequest("GET",
        fmt.Sprintf("https://api.godaddy.com/v2/customers/%s/domains/example.com", customer), nil)
    req.Header.Set("Authorization", "Bearer "+pat)
    req.Header.Set("Accept", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()

    var detail struct {
        Domain string `json:"domain"`
        Status string `json:"status"`
    }
    json.NewDecoder(res.Body).Decode(&detail)
    fmt.Println(detail.Domain, detail.Status)
}

Reference: GET /v2/customers/{customerId}/domains/{domain}.

v2 paths (/v2/customers/{customerId}/domains/...) are preferred for single-domain detail; v1 paths are appropriate for list operations and account-scoped writes.

Use the CLI

After you set up the CLI, you can use it to list domains in your account and fetch full details for one domain.

The following procedure lists domains and fetches domain details using the CLI.

Run the command for your operation:

gddy domain list
gddy domain list --status ACTIVE
gddy domain get example.com

Use the REST API for v2 single-domain detail; the preceding CLI commands use v1 account-scoped endpoints.

Common errors

Status	Most likely cause
`401`	Token missing, expired, or revoked.
`403`	Account doesn't meet requirements for this operation. See Account requirements.
`404` (single-domain GET)	Domain doesn't exist, or isn't owned by the authenticated account.
`429`	Rate limit. Wait `retryAfterSec` and retry.

Full error envelope and retry guidance: Errors.

Update DNS records

Add, replace, or delete A, CNAME, MX, TXT, and other record types.

Update contacts

Change registrant, admin, billing, or tech contacts on a domain you own.

Auto-renew and renewals

Toggle auto-renew, manually renew, redeem from grace period.

Agent & Automation Notes

PermissionsDNS Management, Domain Owner

Scopesdomains.domain:read

Rate limitRate-limited per credential per window. Go to /docs/api-users/rate-limits for current values.

IdempotentYes

DestructiveNo

On failureRead-only. Safe to retry any failure. For paginated cursors, resume from the last successful marker.

API References

Guides

Concepts

Last updated on

Registered domains