---
title: "Widget funnel beacon (fire-and-forget)"
method: POST
path: "/telemetry:connect"
tags: ["Connect"]
---

# Widget funnel beacon (fire-and-forget)

`POST /telemetry:connect`

## Request

- Base URL: `https://api.customdomain.ai/v1`
- URL: `https://api.customdomain.ai/v1/telemetry:connect`
- Auth: HTTP bearer

A PII-free beacon recording which step of the in-modal connect flow a user reached. It exists because server-side counters only observe connections that actually get created, and so are blind to pre-connection drop-off.
`step` and `outcome` are allow-listed server-side and anything unrecognised is folded into a fixed label. A beacon that carries a `session_id` is also stored against the calling application, which is what `GET /analytics/connect` reads; one without it is only counted. No domain, IP or user agent is stored. It **always** answers `204`, including for an invalid token or a malformed body, so telemetry can never block or error the widget; do not branch on its response.

## Request body

- object
  - `step` string: Funnel step label (server-side allow-list).
  - `outcome` string: Outcome label (server-side allow-list).
  - `session_id` string: Random id per widget open, 8 to 64 of [A-Za-z0-9_-].
  - `provider` string: Detected DNS provider id.
  - `rail` 'oauth' | 'domain_connect' | 'manual' | 'api_key' | 'managed_dns'
  - `domain_kind` 'apex' | 'subdomain'
  - `error_code` string: Widget error code, [A-Za-z0-9_] up to 48.
  - `connection_id` string
  - `elapsed_ms` integer: Milliseconds since the widget opened (capped at a day).

## Response `204`

Always. Carries no body and reports no error by design.

---

[API](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api.md) · [All operations](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/customdomain/apis/customdomain-control-plane-api/revisions/34d89cb7a7cd?raw)