# list_bought_domains

Source: https://modulify.ai/docs/api/bought-domains/list-bought-domains

Lists the domains a workspace bought through Modulify, newest first, 25 at a time.

- Title: List bought domains
- Scope: `domains:read`
- Access: Read only
- Endpoint: `POST /v1/list_bought_domains`

These are the registrations the workspace owns, bought on its **Domains** page or with `buy_domain`. They are not the custom domains of a site, which `get_domain_status` reads: a bought domain serves a site only once it is added to that site, with `add_custom_domain` or by `buy_domain` when it was passed `connectProjectId`. Every member of the workspace can list them.

Each row carries `_id`, the `domainId` every bought domain tool takes, `Name`, `State`, `Registered_At`, `Expires_At`, `RenewalPriceCents`, what renewing costs in US cents for `RenewalYears` years, the shortest renewal term, `Locked`, whether the transfer lock is on, `PrivacyEnabled`, `Nameservers`, `DefaultNameservers`, Modulify's nameservers, the ones it started with, `UsesProviderDns`, `ManagedRecordCount`, how many records Modulify keeps in it for the workspace's sites and email domains, `DnsSyncError`, what keeps Modulify from adding one of them or null, and, for a failed domain, `Failure_Reason`.

Four fields report auto-renew. `AutoRenew` is true while Modulify renews the domain itself before it expires, and `AutoRenew_By` is the id of the person whose saved card pays for that, or null. `AutoRenew_Failed_At` and `AutoRenew_Error` say when and why the latest automatic renewal for the current `Expires_At` failed, and are null otherwise.

`RenewBy` is the last day the domain can still be renewed once it has expired, at the normal renewal price. It is null while Name.com has not reported the grace days of the domain's extension yet. After that day Name.com removes the domain from the account and it shows as `released`, and Modulify has no redemption or restore step. See [After a domain expires](https://modulify.ai/docs/publish/buy-a-domain#after-a-domain-expires).

Three fields report whether Name.com has confirmed the registrant's email, which it asks for by emailing the registrant a link after a registration and after some changes of the registrant.

| `Verification` | Meaning |
| --- | --- |
| `verified` | The link was clicked |
| `pending` | Nobody has clicked the link yet. `Verification_Due_At` is the deadline once Name.com reported it, and null before |
| `suspended` | Nobody clicked the link in time, so Name.com suspended the domain and its sites and email stop working until somebody does |
| null | Not known yet, or the domain is not registered |

`Verification_Resend_At` is when the workspace owner can have Name.com send the link again from the domain's page, or null when they can now. See [Verify the owner email](https://modulify.ai/docs/publish/buy-a-domain#verify-the-owner-email).

| `State` | Meaning |
| --- | --- |
| `pending` | The registrar has not confirmed the registration yet, so `add_custom_domain` still refuses it |
| `active` | Registered, with more than 30 days left |
| `expiring` | In its last 30 days |
| `expired` | `Expires_At` has passed. It can still be renewed until `RenewBy` |
| `failed` | The order did not go through and the payment was refunded |
| `released` | The workspace no longer holds it at Name.com, because it moved to another registrar or lapsed and was deleted or registered again |

A failed or released domain can only be cleared from the list with `remove_domain_from_list`. `UsesProviderDns` is true while the domain uses Modulify's nameservers: the records the DNS record tools change are then the ones that answer for it, and Modulify adds and removes the records the workspace's sites and email domains under it need by itself. A domain with `AutoRenew` true is renewed by Modulify before `Expires_At`, see `set_domain_auto_renew`. Name.com's own auto renew always stays off, so any other domain is renewed only once its renewal is paid, and the tool tells the client to offer `renew_domain` when one is expired, when `AutoRenew_Error` is set, or when one with `AutoRenew` false is expiring.

Narrow the list with `term` and `status`, and order it with `sort`. It returns 25 per page, so pass `offset` to go further, and the response carries the total `count`. See [Read the list](https://modulify.ai/docs/publish/buy-a-domain#read-the-list).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/list_bought_domains`, sending the inputs below as a JSON object. The token needs the `domains:read` scope.

It only reads and changes nothing, so retrying it is safe.

```bash
curl -X POST https://api.modulify.ai/v1/list_bought_domains \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID"}'
```

Over MCP, the same method is the [list_bought_domains tool](https://modulify.ai/docs/mcp/bought-domains/list-bought-domains).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string | Yes | The workspace id, from `list_workspaces`. |
| `term` | string | No | Keeps only domains whose name matches this text. Up to 253 characters. |
| `status` | string | No | Keeps only domains in one state: `pending`, `active`, `expiring`, `expired`, `failed` or `released`. |
| `sort` | string | No | The order to list them in: `newest`, the default, `oldest`, `name`, or `expires`, which puts the soonest expiry first and domains with no expiry date yet, such as pending or failed ones, last. |
| `offset` | integer | No | How many domains to skip, 0 or more. Pages are 25 long. Defaults to 0. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.