Widget funnel beacon (fire-and-forget)

Widget funnel beacon (fire-and-forget): CustomDomain™ API reference in the analytics group. Covers parameters, request body, responses and error codes.

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 is stored, and nothing the end user typed. With each stored beacon the control plane keeps the end user's IP address and country (from the request, believed only through Cloudflare), and the session it belongs to: at its first beacon the address, the region and city Cloudflare derived, and the device type, operating system and browser parsed from the User-Agent (the string itself is not stored); at every beacon the step, rail, provider and outcome. Addresses are kept for as long as the account exists, unless the deployment's IP_RETENTION_DAYS sets a window. 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.

Authorization

apiKey

AuthorizationBearer <token>

Long-lived tenant API key, cd_live_… (production) or cd_test_… (staging, development), stored hashed. Keys created before the switch to cd_ start with sk_live_… / sk_test_… and are still accepted. Scoped to the owning application's tenant.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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?string

Value in

"oauth"
"domain_connect"
"manual"
"api_key"
"managed_dns"
"cloud_browser"

domain_kind?string

Value in

"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).

client?

Optional. What the widget reports about its surroundings, recorded on the session while the session has no value for it yet. Every field is optional, and a value outside its range or alphabet is dropped; unlike the beacon's own fields an unknown field here is ignored, and an object larger than 2 KiB is ignored whole.

Response Body

curl -X POST "https://example.com/telemetry:connect" \  -H "Content-Type: application/json" \  -d '{}'

Empty