# Registered domains (https://developer.godaddy.com/en/docs/api-users/manage-domains/list)



## 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.

<Callout type="info">
  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.
</Callout>

`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](https://developer.godaddy.com/docs/api-users/auth) and [Quickstart](https://developer.godaddy.com/docs/api-users/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](https://developer.godaddy.com/docs/api-users/pagination).

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

* Run the following command for your preferred language:

<Tabs items={['curl', 'Node', 'Python', 'Go']}>
  <>
    <Tab value="curl">
      ```bash
      curl -s "https://api.godaddy.com/v1/domains?limit=100" \
        -H "Authorization: Bearer $GODADDY_PAT" \
        -H "Accept: application/json"
      ```
    </Tab>

    <Tab value="Node">
      ```js
      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));
      ```
    </Tab>

    <Tab value="Python">
      ```python
      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"))
      ```
    </Tab>

    <Tab value="Go">
      ```go
      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)
          }
      }
      ```
    </Tab>
  </>
</Tabs>

### 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`](https://developer.godaddy.com/docs/references/rest/domains/v1/manage-domain-settings).

## 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:

<Tabs items={['curl', 'Node', 'Python', 'Go']}>
  <>
    <Tab value="curl">
      ```bash
      curl -s "https://api.godaddy.com/v1/domains/example.com" \
        -H "Authorization: Bearer $GODADDY_PAT" \
        -H "Accept: application/json"
      ```
    </Tab>

    <Tab value="Node">
      ```js
      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);
      ```
    </Tab>

    <Tab value="Python">
      ```python
      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"])
      ```
    </Tab>

    <Tab value="Go">
      ```go
      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)
      }
      ```
    </Tab>
  </>
</Tabs>

Reference: [`GET /v1/domains/{domain}`](https://developer.godaddy.com/docs/references/rest/domains/v1/manage-domain-settings).

## 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:

<Tabs items={['curl', 'Node', 'Python', 'Go']}>
  <>
    <Tab value="curl">
      ```bash
      curl -s "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/example.com" \
        -H "Authorization: Bearer $GODADDY_PAT" \
        -H "Accept: application/json"
      ```
    </Tab>

    <Tab value="Node">
      ```js
      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);
      ```
    </Tab>

    <Tab value="Python">
      ```python
      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"])
      ```
    </Tab>

    <Tab value="Go">
      ```go
      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)
      }
      ```
    </Tab>
  </>
</Tabs>

Reference: [`GET /v2/customers/{customerId}/domains/{domain}`](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings).

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](https://developer.godaddy.com/docs/api-users/cli-setup), 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:

```bash
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](https://developer.godaddy.com/docs/api-users/auth#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](https://developer.godaddy.com/docs/api-users/errors).

## Next

<Cards>
  <Card title="Update DNS records" description="Add, replace, or delete A, CNAME, MX, TXT, and other record types." href="/docs/api-users/manage-domains/dns" />

  <Card title="Update contacts" description="Change registrant, admin, billing, or tech contacts on a domain you own." href="/docs/api-users/manage-domains/update-contacts" />

  <Card title="Auto-renew and renewals" description="Toggle auto-renew, manually renew, redeem from grace period." href="/docs/api-users/manage-domains/renewals" />
</Cards>