OpenAPI beacon

Every fill page (direct link, embed, or popup) sends batched analytics events to a single endpoint. This is what powers Reading Insights — you generally never call it directly, but it’s useful to understand if you’re debugging traffic numbers or building a custom fill client.

Try it in the API playground

This endpoint is also published as OpenAPI — open the interactive playground to send a real request against your app.

Request

endpoint

Route throttle 60 requests/minute per client, plus a per-form × IP event budget (default 120 events/minute). web middleware, no auth required (public fill pages are anonymous). Only active forms accept events.

string

required

A UUID identifying the visitor’s fill session.

integer

Numeric form ID. Either this or form_slug is required.

string

The form’s public slug, if form_id isn’t known client-side.

array

required

1–20 event objects per batch.

Event object

string

required

One of: visit_start, page_view, page_leave, field_interact, started_answering, submit, heartbeat.

string

Which page/block the event refers to.

string

ISO timestamp within now − 5 minutes … now + 2 minutes. Outside that window the batch is rejected (422). Omitted timestamps use server time.

integer

0 to 86,400,000 (24h ceiling).

string

Parsed client hints, sent as plain strings.

string

ISO-2 country code and city, when geo IP resolution is enabled.

string

Standard UTM parameters captured from the visit.

string

A hashed key used to de-duplicate a respondent across events without exposing PII.

{
  "form_slug": "contact-us",
  "session_id": "6f1e2c2a-9b3d-4e6a-8b2b-9d7c0a1e2f33",
  "events": [
    { "event": "visit_start", "occurred_at": "2026-08-01T14:00:00Z" },
    { "event": "page_view", "page_id": "page_1" },
    { "event": "field_interact", "block_id": "email_field" },
    { "event": "submit", "duration_ms": 42311 }
  ]
}

curl -X POST "https://your-app.test/flex-forms/analytics/beacon" \
  -H "Content-Type: application/json" \
  -d '{
    "form_slug": "contact-us",
    "session_id": "6f1e2c2a-9b3d-4e6a-8b2b-9d7c0a1e2f33",
    "events": [{ "event": "page_view", "page_id": "page_1" }]
  }'

Response

boolean

true when the batch was accepted and queued for processing.

integer

Number of events accepted from the batch.

Show 200 OK

{ "ok": true, "queued": 4 }

Show 422 — invalid payload

{
  "message": "Invalid analytics payload.",
  "errors": { "form_id": ["A form_id or form_slug is required."] }
}

Show 404 — form not found or inactive

{ "message": "Form not found." }

Show 429 — per-form event budget exceeded

{ "message": "Too many analytics events." }

Events are queued for asynchronous processing (RecordAnalyticsEventsJob) — a 200 response means the batch was accepted, not that Insights has been recomputed yet. Bot/crawler traffic is flagged and excluded from Insights KPIs during processing, not at ingestion time.

This endpoint intentionally accepts unauthenticated requests from any public fill page. Don’t rely on it as a general-purpose event pipe for your own app — it only accepts the fixed event vocabulary above, scoped to an active form.

APIs & config

Extensibility

Architecture

Try it in the API playground

Request

Event object

Response

Try it in the API playground

​Request

​Event object

​Response

Request

Event object

Response