# List connections

> List connections: reference page for this CustomDomain™ API operation in the connections group. Covers parameters, request body, responses and error codes.

Source: https://docs.customdomain.ai/docs/api-reference/connections/listConnections

## `GET https://api.customdomain.ai/v1/connections`

With an API key: every connection across the tenant's applications (optional `?app_id=` and `?status=` filters). With an `app`-scoped widget JWT or a delegated agent token: the calling application's connections (`app_id` is ignored; the scope is fixed to that application). A `connect`-scoped widget JWT (an end user's) is refused with `403`.

**The response is paginated and always bounded.** `limit` defaults to 500 and is clamped to 1000; `next_cursor` is present **only** when more rows remain. To read every connection, follow `next_cursor` until it is absent. Counting rows client-side is not required; see `GET /connections:count`.

A `status` outside the enum is rejected with **400** (it used to reach the database and surface as a 500).

Every row carries `dns_hosting`: who runs the domain's DNS. To find the domains CustomDomain™ runs the DNS for, ask for `?dns_hosting=hosted`; the filter is applied in the database, so a page is full and `next_cursor` keeps walking the matching rows. A `dns_hosting` outside the enum is rejected with **400**. Test mode connections never match it.

A delegated agent token needs `domains:read`. It reads no `end_user_ref`, the platform's id for its end user, on any row (an API key reads it).

### Authentication

`apiKey`, `widgetJWT`, `agentToken`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app_id` | query | string | no |  |
| `status` | query | `pending`, `propagating`, `live`, `failed` | no |  |
| `dns_hosting` | query | `hosted`, `moving`, `any` | no | Keep only the connections by who runs their DNS. `hosted`: the nameservers point at a zone we run, so the domain's DNS is served from it. `moving`: the zone is being set up or the nameservers are being moved. `any`: every domain with DNS hosting in play (hosted, moving or failed). Omit for all connections. |
| `limit` | query | integer | no | Rows per page. Defaults to 500; values above 1000 are clamped to 1000. |
| `cursor` | query | string | no | Opaque keyset cursor taken verbatim from a previous response's `next_cursor`. Omit for the first page. |

### Responses

| Status | Description |
| --- | --- |
| `200` | Connections |
| `400` | Error envelope: {code, title, details}. |
| `401` | Error envelope: {code, title, details}. |
| `403` | Error envelope: {code, title, details}. |

### `200` response body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `connections` | array of object | yes |  |
| `count` | integer | yes | Rows in THIS page, not the tenant total. |
| `next_cursor` | string | no | Present only when further rows remain. Pass it back as `?cursor=` to fetch the next page. |

The full specification is served at `GET https://api.customdomain.ai/v1/openapi.json`.