---
operationId: "listProjectBranchCustomDomains"
method: "GET"
path: "/projects/{project_id}/branches/{branch_id}/custom-domains"
tag: "functions"
stability: "beta"
interfaces: ["api", "sdk"]
---
> API Reference / Functions / List the custom domains on a branch

## GET /projects/{project_id}/branches/{branch_id}/custom-domains

Lists all custom domains registered on the branch, across every target
entity.

**Note**: This endpoint is currently in Beta.


### Parameters

- `project_id` (string, path, required)
  The Neon project ID
- `branch_id` (string, path, required)
  The Neon branch ID
- `cursor` (string, query, optional)
  A cursor to use in pagination. A cursor defines your place in the data list. Include `response.pagination.next` in subsequent API calls to fetch next page of the list.
- `limit` (integer, query, optional)
  Specify a value from 1 to 1000 to limit number of domains in the response

### Response (200)

- `custom_domains` (array, optional)
  - `domain` (string, required)
    The registered custom domain (normalized, lowercase).
  - `entity_type` (string, required)
    The kind of branch entity the domain targets. Possible values:
    `function` (v1 supports only `function`). Not an `enum`: new values may
    ship in later spec versions — treat any undocumented value as unknown.
    
  - `entity_id` (string, required)
    The target entity's identifier within the branch. For `function` this
    is the function slug.
    
  - `cname_target` (string, required)
    The hostname the customer must point their custom domain at with a
    CNAME record. Empty when the serving region has no custom-domains
    front door configured. This is the activation input: point DNS here
    and the domain goes live (see `status`) once a certificate is issued
    on the first request.
    
  - `status` (string, optional)
    The domain's current validity, computed by a background check:
    `pending` (still converging — point your CNAME at `cname_target` and
    wait), `active` (live: DNS resolves to the edge, the CA is authorized,
    and routing is published), or `error` (a fixable problem — see
    `status_reason`). Not an `enum`: treat any undocumented value as
    unknown. May be absent briefly right after registration.
    
  - `dns_status` (string, optional)
    The DNS + CAA portion of the check: `pending` (no records yet), `ok`
    (resolves to our edge and the CA is authorized), `misconfigured` (your
    CNAME does not resolve to our edge), or `caa_blocked` (your CAA records
    forbid Let's Encrypt). Not an `enum`.
    
  - `binding_status` (string, optional)
    Whether Neon's internal routing for the domain is published:
    `pending`, `present`, or `missing`. `missing` is an internal fault
    surfaced for support. Not an `enum`.
    
  - `status_reason` (string, optional)
    A short, stable machine-readable reason for a non-active `status`
    (e.g. `cname-not-pointing-at-edge`, `caa-blocks-lets-encrypt`,
    `binding-missing`), suitable for keying an actionable hint. Empty when
    active or pending.
    
- `pagination` (object, optional)
  To paginate the response, issue an initial request with `limit` value. Then, add the value returned in the response `.pagination.next` attribute into the request under the `cursor` query parameter to the subsequent request to retrieve next page in pagination. The contents on cursor `next` are opaque, clients are not expected to make any assumptions on the format of the data inside the cursor.
  - `next` (string, optional)
    Cursor for the next page of results. Pass it as the `cursor` query parameter on the next request. Absent on the last page.
  - `sort_by` (string, optional)
    Field by which the results were sorted, echoing the request's sort_by parameter.
  - `sort_order` (string, optional)
    Sort order active for this page. Pass back as `sort_order` in the next request to maintain consistent ordering. Valid values are `asc` and `desc`.

### Code examples

```bash
curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/custom-domains" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```typescript
import { createNeonClient, raw } from '@neon/sdk';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY });
const { data } = await raw.listProjectBranchCustomDomains({
  client: neon.client,
  path: {
    project_id: process.env.PROJECT_ID,
    branch_id: process.env.BRANCH_ID
  }
});
```

### Errors

**default**
General Error.

The request may or may not be safe to retry, depending on the HTTP method, response status code,
and whether a response was received.

- If no response is returned from the API, a network error or timeout likely occurred.
- In some cases, the request may have reached the server and been successfully processed, but the response failed to reach the client. As a result, retrying non-idempotent requests can lead to unintended results.

The following HTTP methods are considered non-idempotent: `POST`, `PATCH`, `DELETE`, and `PUT`. Retrying these methods is generally **not safe**.
The following methods are considered idempotent: `GET`, `HEAD`, and `OPTIONS`. Retrying these methods is **safe** in the event of a network error or timeout.

Any request that returns a `503 Service Unavailable` response is always safe to retry.

Any request that returns a `423 Locked` response is safe to retry. `423 Locked` indicates that the resource is temporarily locked, for example, due to another operation in progress.

- `request_id` (string, optional)
  Unique identifier for the request, useful for debugging.
  You can set this value manually by including an `X-Request-ID` header in the request. If not provided, the value will be generated automatically.
  
- `code` (string, required)
  Machine-readable code classifying the error type. See `message` for a human-readable explanation.
  Default: ``
- `message` (string, required)
  Error message