> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [/docs/api/domains/openapi.json](/docs/api/domains/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-22.

# Domains: List domains

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

One endpoint of [Domains](/docs/api/domains.md). Authentication, workspaces and errors: [/docs.md](/docs.md).

## List domains

`GET /v1/domains` - operationId `domains.list`

| Permission | Rate limit |
| --- | --- |
| Delivery view | 12,000 requests a minute per API key |

Returns the workspace's domains, one page at a time. Each item has the same shape as
`GET /v1/domains/{domainId}`.

`limit` is from 1 to 200 and defaults to 50. To get the next page, send the `nextCursor` of the
previous page as `cursor`.

Errors:

- `400 validation_failed`: `limit` is out of range, or `cursor` did not come from this list.

Requires Delivery view.

[Try it on developer.ken.so](https://developer.ken.so/reference/#kenso-api/tag/domains/GET/v1/domains)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string | no | The `nextCursor` from the previous page. Omit it for the first page. |
| `limit` | query | integer (int32) | no | Domains per page, from 1 to 200. Default 50. |
| `Ken-Version` | header | string, one of: 2026-11-02, 1.1 | no | The API version, a date in `YYYY-MM-DD` form. `1.1` is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and `404` where the path exists only in this version. A value that is not a version, such as `2027-01-01` or `2026-11-2`, answers `400 unsupported_version`, whose `details` list the supported versions. |
| `X-Ken-Workspace-Id` | header | integer (int64) | no | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers `400 workspace_required`. A workspace you are not a member of answers `404 not_found`. |

### Response 200

`data` is a list of `Domain`. Each item has these fields. The response also carries `pagination`.

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer (int64) | The domain's id. |
| `name` | string | The domain name, such as `acme-mail.com`. |
| `status` | string | The domain's state: `active`, `pending_setup` (Kenso is still setting it up), `paused`, `expired`, `blacklisted`, `banned` or `deleted`. |
| `source` | string | Where the domain came from: `platform_purchased` (Kenso bought it for you) or `imported` (you brought it). |
| `providerHosted` | boolean | True when your email provider hosts the domain and Kenso does not run it: Kenso keeps the domain only to check the mailboxes you connected on it. The domain list leaves it out, and it cannot be deleted. Importing the domain moves it to Kenso. |
| `expirationDate` | string (date-time) | When the domain's registration expires, in UTC. Omitted when unknown. |
| `daysLeft` | integer (int32) | Whole days left until `expirationDate`, rounded down. Negative once the domain has expired. Omitted when the expiry is unknown. |
| `isExpiring` | boolean | True when the registration expires within the next 30 days and has not expired yet. |
| `autoRenew` | boolean | True when Kenso renews the domain's registration before it expires. |
| `autoRenewEligible` | boolean | True when Kenso can renew the domain, which holds for the domains Kenso bought. |
| `registrar` | string | The registrar that holds the domain's registration. Omitted when unknown. Prefer registrarKind. |
| `registrarKind` | string | Who holds the domain's registration, in neutral words: `kenso` when Kenso registered the domain, `other` for any other registrar. Omitted when unknown. |
| `dnsProvider` | string | The DNS host that serves the domain's records. Omitted when unknown. Prefer dnsHostKind. |
| `dnsHostKind` | string | Who serves the domain's DNS records, in neutral words: `kenso` when Kenso hosts the zone, `other` for any other DNS host. Omitted when unknown. |
| `clickRateTrackingEnabled` | boolean | True when click tracking through this domain is on. |
| `trackingDnsStatus` | string | Whether the domain's DNS points at Kenso's redirect servers: `verified`, `unchecked` (not checked yet) or `dead` (several checks in a row failed). Omitted when the domain has no tracking settings. |
| `maskingEnabled` | boolean | True when visitors to the domain see the forwarding URL's page while the address bar keeps the domain's name. Read-only: an update that sends it is refused. |
| `rampUpDays` | integer (int32) | Over how many days Kenso raises the daily send limit of the domain's inboxes to their full limit, from 0 to 30. 0 means no ramp-up. Omitted when not set. |
| `rampUp` | DomainRampUp | Where the domain is in its ramp-up today. Omitted when Kenso could not read it. |
| `redirectUrl404` | string | The forwarding URL: where Kenso sends people who open the domain in a browser. Omitted when none is set. |
| `openPixelHostname` | string | The host that serves the open tracking pixel in one-to-one emails, such as replies, sent from this domain. Omitted when none is set. |
| `openPixelStatus` | string | State of `openPixelHostname`: `none` (no host), `pending` (set but not verified yet), `verified` (Kenso adds the pixel through it) or `disabled`. Omitted when the domain has no tracking settings. |
| `campaignPixelHost` | CampaignPixelHost | Where campaign emails from this domain load their open tracking pixel. Omitted when Kenso could not read it. |
| `catchAllEmail` | string | The address that gets mail sent to unknown addresses on the domain. Only returned by the update that set it; omitted otherwise. |
| `hasError` | boolean | True when setting up the domain or its nameservers failed. `statusReason` says why. |
| `statusReason` | string | Why the domain needs attention, in one short sentence. Omitted when nothing is wrong. |
| `isPrimary` | boolean | True when this is one of the workspace's own domains: its email domain or a domain listed under Settings > Company. Members' primary inboxes sit on these domains, and an inbox's `isPrimary` follows the same rule. |
| `tagIds` | array of integer (int64) | Ids of the domain's tags. Empty when it has none. |
| `retirement` | DomainRetirement | The window in which Kenso keeps catching replies after the domain was retired: the open window, else the last one that ended. Omitted for a domain that was never retired. |
| `replacedBy` | DomainReplacement | The domain Kenso bought to replace this one, for example after this one landed on a blocklist. Omitted when nothing replaced it. |
| `health` | DomainHealthStatus | The domain's health: its rung on Ken's domain health ladder (`good`, `watch`, `throttle`, `quarantine`, `block`), why, and the next step. Shown only in a workspace where domain health is on; omitted otherwise and for a domain not rated yet. |
| `nameservers` | DomainNameservers | For a domain you imported: the nameservers to set at its registrar, the ones it has now, and where the change stands. Only `GET /v1/domains/{domainId}` returns it. Omitted for a domain Kenso bought. |
| `registrarInfo` | DomainRegistrar | For a domain you imported: its registrar, from public RDAP, with the key of that registrar's nameserver steps. Only `GET /v1/domains/{domainId}` returns it. Omitted for a domain Kenso bought and when the lookup failed. `registrar` above is a different field: the registrar Kenso has on file, as a name. |

### Request

```bash
curl -X GET "https://api.ken.so/v1/domains?limit=50" \
  -H "Authorization: Bearer $KENSO_API_KEY" \
  -H "Ken-Version: 2026-11-02" \
  -H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"
```

### Example response

```json
{
  "success": true,
  "data": [
    {
      "id": 812,
      "name": "acme-mail.com",
      "status": "string",
      "source": "string",
      "providerHosted": true,
      "expirationDate": "2026-09-23T15:02:11Z",
      "daysLeft": 1,
      "isExpiring": true,
      "autoRenew": true,
      "autoRenewEligible": true,
      "registrar": "string",
      "registrarKind": "string",
      "dnsProvider": "string",
      "dnsHostKind": "string",
      "clickRateTrackingEnabled": true,
      "trackingDnsStatus": "string",
      "maskingEnabled": true,
      "rampUpDays": 1,
      "rampUp": {
        "days": 1,
        "dayIndex": 1,
        "isComplete": true
      },
      "redirectUrl404": "string",
      "openPixelHostname": "string",
      "openPixelStatus": "string",
      "campaignPixelHost": {
        "status": "string",
        "hostname": "string",
        "requiredRecord": {
          "type": "CNAME",
          "name": "link.acme-mail.com",
          "value": "string"
        }
      },
      "catchAllEmail": "jane@example.com",
      "hasError": true,
      "statusReason": "string",
      "isPrimary": true,
      "tagIds": [
        812
      ],
      "retirement": {
        "state": "string",
        "captureUntil": "2026-09-23T15:02:11Z",
        "releasedAt": "2026-09-23T15:02:11Z",
        "renewalEndsWindowEarly": true
      },
      "replacedBy": {
        "id": 812,
        "name": "string"
      },
      "health": {
        "rung": "string",
        "reason": "string",
        "message": "string",
        "action": "string",
        "since": "2026-09-23T15:02:11Z",
        "until": "2026-09-23T15:02:11Z",
        "evaluatedAt": "2026-09-23T15:02:11Z"
      },
      "nameservers": {
        "expected": [
          "string"
        ],
        "current": [
          "string"
        ],
        "status": "string",
        "waitingForCredits": true,
        "requiredMillicredits": 1,
        "availableMillicredits": 1
      },
      "registrarInfo": {
        "name": "string",
        "ianaId": 812,
        "guide": "godaddy"
      }
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "totalCount": 1,
    "isTotalCapped": true
  }
}
```

## Types

Each named type the tables above use, nested ones included.

### DomainRampUp

A domain's progress through its ramp-up.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `days` | integer (int32) | no | Length of the ramp-up in days. 0 means the domain does not ramp up. |
| `dayIndex` | integer (int32) | no | Today's day of the ramp-up, from 1 to `days`, counted in UTC calendar days from the day it started (1 before it starts). Stays at `days` once the ramp-up is over, and is 0 when `days` is 0. |
| `isComplete` | boolean | no | True when the domain's inboxes send at their full daily limit: the ramp-up is over, the domain has none, or ramp-up is turned off. |

### CampaignPixelHost

Where campaign emails from a domain load their open tracking pixel.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | no | Which host serves the pixel. `link`: `link.{domain}` serves it. `unsub`: the domain's DNS is in Kenso's DNS account, where Kenso creates `unsub.{domain}` itself. `none`: the domain has no host and Kenso cannot create one, so campaign emails from it go out without a pixel; `requiredRecord` names the record it needs. `unknown`: Kenso has not tried a host there yet (a domain with no inbox, or the workspace's website domain), or is still trying. |
| `hostname` | string | no | The pixel host for `link` and `unsub`, else omitted. For `unsub` it is the host Kenso creates, which may not serve yet. |
| `requiredRecord` | DomainDnsRecord | no | Set with `none` when the domain's DNS is outside Kenso: the CNAME record to add for `link.{domain}`. Once public DNS shows it, Kenso registers the host on its own, usually within an hour. Omitted otherwise. |

### DomainRetirement

The reply capture window of a retired domain. Until `captureUntil`, Kenso receives the domain's mail, so replies to emails sent from it still arrive.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | no | The window's state: `pending` (the window is opening; Kenso retries every 15 minutes until the DNS change is confirmed), `applied` (Kenso receives the replies), `release_pending` (the window is closing), `released` (closed) or `failed` (closed without ever applying, because the domain's DNS left Kenso's DNS account). |
| `captureUntil` | string (date-time) | no | When the capture window ends, in UTC. |
| `releasedAt` | string (date-time) | no | When the window ended, in UTC. Omitted while it is open. |
| `renewalEndsWindowEarly` | boolean | no | True while the window is open, auto-renew is off and the registration expires before `captureUntil`. The domain can then lapse, and a new owner would get the replies. |

### DomainReplacement

A domain that Kenso bought to replace another.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | no | The replacement domain's id. |
| `name` | string | no | The replacement domain's name. |

### DomainHealthStatus

A domain's health on Ken's domain health ladder, customer-facing: `rung` is `good`, `watch`, `throttle`, `quarantine` or `block`; `reason` is a vendor-neutral code; `message` and `action` are sentences to show a user (`action` omitted when there is nothing to do); `until` is the end of a quarantine.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rung` | string | no |  |
| `reason` | string | no |  |
| `message` | string | no |  |
| `action` | string | no |  |
| `since` | string (date-time) | no |  |
| `until` | string (date-time) | no |  |
| `evaluatedAt` | string (date-time) | no |  |

### DomainNameservers

Where an imported domain's nameserver change stands.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected` | array of string | no | The nameservers to set at the domain's registrar: the ones Kenso's DNS assigned to the zone Kenso created for the domain, lowercased and sorted. |
| `current` | array of string | no | The nameservers the domain has now, from a live DNS lookup (up to 10 minutes old), lowercased and sorted. Empty when the lookup failed. |
| `status` | string | no | `pending` (Kenso is waiting for the change, or sees it and is finishing setup), `action_required` (no change after 24 hours: change the nameservers at the registrar) or `active` (the domain is set up). Kenso checks every 15 minutes; call `POST /v1/domains/{domainId}/check-nameservers` to check now. |
| `waitingForCredits` | boolean | no | True when the nameservers already point at Kenso but setup waits until the workspace has the credits to pay the first month of the domain's mailboxes. Add credits; setup then continues on the next check. |
| `requiredMillicredits` | integer (int64) | no | Credits the first month of the domain's mailboxes costs, in thousandths of a credit. Set only with `waitingForCredits`. |
| `availableMillicredits` | integer (int64) | no | The workspace's credit balance, in thousandths of a credit. Set only with `waitingForCredits`. |

### DomainRegistrar

A domain's registrar, from public RDAP.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | The registrar's name as RDAP gives it, such as `GoDaddy.com, LLC`. |
| `ianaId` | integer (int32) | no | The registrar's IANA Registrar ID, such as `146`. Null when RDAP does not give one. |
| `guide` | string | no | The key of that registrar's nameserver steps: `godaddy`, `namecheap`, `porkbun`, `cloudflare`, `squarespace`, `google`, `ionos`, `ovh`, `gandi`, `hover`, `namecom`, `dynadot`, `enom`, `networksolutions` or `other`. |

### DomainDnsRecord

A DNS record to add at the domain's DNS host.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | no | The record type, such as `CNAME`. |
| `name` | string | no | The host name the record is for, such as `link.acme-mail.com`. |
| `value` | string | no | The value the record points to. |
