---
title: "Custom domains across every customer site"
method: GET
path: "/stats/custom-domains"
tags: ["Stats"]
---

# Custom domains across every customer site

`GET /stats/custom-domains`

## Request

- Base URL: `https://api.nippy.host`
- URL: `https://api.nippy.host/stats/custom-domains`
- Auth: `bearer` (a scheme the document does not define)

Admin-only paginated directory of every custom domain, newest first, with its provisioning status and failure reason, the site it points at, and the owning plan and email. Filterable by search (hostname, subdomain or owner email) and by status; `pending` matches both pending states. Read-only.

## Query parameters

- `search` string
- `status` 'pending_dns' | 'pending_ssl' | 'active' | 'failed' | 'disabled' | 'pending'
- `page` number
- `pageSize` number

## Response `200`

- APIPaginatedAdminDomainsResponse
  - `data` APIAdminDomain[], required
    - `id` string, required: Custom domain id (UUID).
    - `hostname` string, required: The custom hostname.
    - `status` 'pending_dns' | 'pending_ssl' | 'active' | 'failed' | 'disabled', required: Provisioning status.
    - `failureReason` string, nullable, required: Why provisioning failed; null unless the domain failed.
    - `isCompanion` boolean, required: Whether the row is an automatic companion of another domain (for example the `www` pair of an apex).
    - `verifiedAt` string, nullable, required: When the domain became active (ISO 8601); null until then.
    - `createdAt` string, required: When the domain was added (ISO 8601).
    - `siteId` string, required: Id of the site the domain points at (UUID).
    - `subdomain` string, nullable, required: Subdomain of that site; null if the site no longer exists.
    - `siteStatus` 'pending' | 'awaiting_verification' | 'live' | 'inactive' | 'suspended', nullable, required: Lifecycle status of that site; null if it no longer exists.
    - `plan` 'free' | 'basic' | 'pro' | 'max', required: The owning account’s plan tier (`free` when none).
    - `ownerUserId` string, nullable, required: Id of the user who owns the account; null if none.
    - `ownerEmail` string, nullable, required: Email of that owner; null if none.
  - `page` number, required
  - `pageSize` number, required
  - `total` number, required
  - `totalPages` number, required

## Other responses

- `403`: Admin access required

---

[API](https://skmtc.dev/nippy/apis/nippy-backend-api.md) · [All operations](https://skmtc.dev/nippy/apis/nippy-backend-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nippy/apis/nippy-backend-api/revisions/7ab23f040a55?raw)