---
title: "Record a widget or site analytics event"
method: POST
path: "/api/track"
tags: ["Analytics"]
---

# Record a widget or site analytics event

`POST /api/track`

Records one visitor event (page view, widget open, message sent, identify, purchase) against a Clarm widget. Requests are proxied same-origin to the Clarm analytics service, which authenticates the caller from the widget token or widget id in the payload. Events for a visitor who has opted out should carry `tracking_disabled: true`, which is accepted and discarded.

## Request body

- TrackEventRequest — One analytics event from a Clarm widget or a site using the Clarm tracking helper.
  - `event` string, required — Event name, for example `page_view`, `widget_open`, `message_sent`, `identify`, or `purchase`.
  - `visitor_id` string, required — Stable pseudonymous identifier for the visitor.
  - `widget_id` string — Public widget identifier that authenticates the event when no token is supplied.
  - `organization_id` string — Workspace the widget belongs to. Resolved server-side when omitted.
  - `page_url` string, uri — URL the event happened on.
  - `page_title` string — Document title of that page.
  - `referrer` string — Referrer of that page view.
  - `timestamp` string, date-time — When the event happened. Defaults to receipt time.
  - `user_agent` string — Client user agent. Defaults to the request header.
  - `widget_session` string — Widget session identifier, when a widget is open.
  - `chat_session_id` string — Conversation identifier, when a chat is running.
  - `has_used_widget` boolean — Whether this visitor has interacted with the widget before.
  - `tracking_disabled` boolean — Set when the visitor opted out. The event is accepted and discarded.
  - `utm_params` UtmParams — Campaign attribution recorded alongside the event.
    - `utm_source` string — Campaign source.
    - `utm_medium` string — Campaign medium.
    - `utm_campaign` string — Campaign name.
    - `utm_content` string — Campaign content variant.
    - `utm_term` string — Campaign term.
  - `data` object — Event-specific payload, for example identify traits or purchase value.

## Response `200`

Event accepted, or discarded because the visitor opted out.

- TrackEventResponse — Confirmation that an event was recorded.
  - `success` boolean, required — True when the event was accepted.
  - `event_id` string — Identifier of the stored event.
  - `goals_achieved` integer — How many configured goal rules this event satisfied.
  - `tracking_authenticated` boolean — Whether the caller presented a verified widget token.
  - `side_effects_suppressed` boolean — Whether downstream integrations were skipped for this event.
  - `message` string — Human-readable confirmation.

## Other responses

- `400` — The payload was missing `event` or `visitor_id`, or the widget id was malformed.
- `401` — No usable widget credential was supplied, or the widget token failed verification.
- `403` — The widget is not permitted to record this event.
- `429` — Too many events for this widget and visitor.
- `500` — The event could not be recorded.
- `502` — The analytics service could not be reached.

---

[API](https://skmtc.dev/clarm/apis/clarm-public-api.md) · [All operations](https://skmtc.dev/clarm/apis/clarm-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/clarm/clarm-public-api/revisions/ff890a5d2a91/schema)