Engagement

Open Analytics → Explore → Engagement. Choose the action that means someone used your product, add event filters, and select daily, weekly or monthly activity. Analyze engagement updates the lifecycle chart and two frequency distributions. The URL preserves the analysis and environment.

An empty event includes pageviews and custom events. Identity, page-leave, session-end and web-vital telemetry are excluded, even if named explicitly. Every matching event uses the same filters, including historical events used for classification. This is behavioral activity; it does not use CRM stages.

Lifecycle

Each complete calendar period compares with its previous period:

The first three states add up to active visitors. Dormant visitors are separate; they are counted once when becoming inactive, not repeatedly in later empty periods. A visitor can transition between states across periods. First seen does not prove the visitor is a new customer.

View period counts includes empty periods and partial periods. Partial periods report only observed active visitors; their lifecycle states are unavailable (null). A lifecycle comparison also needs the entire previous calendar period to fall within retained history. It may precede the selected date range. The current period must fit entirely inside the selected range and available retention window.

Weeks start Monday. Months follow actual calendar boundaries. Dates use the application's timezone, including daylight-saving changes.

Frequency

Summary totals and both distributions use complete selected periods only:

• Actions per visitor: the number of matching events per visitor across those periods.
• Active periods per visitor: how many of those periods contain at least one matching event for that visitor.
• Repeat visitors: visitors active in at least two complete periods.
• Average active periods: total visitor/period occurrences divided by active visitors. Complete periods with zero activity remain in the available period count.

Bins are 1, 2, 3–5, 6–10, 11–20 and 21+. Both charts use visitors active in at least one complete period as the denominator. People who never performed the selected action are outside this population. Multiple actions in one period raise event frequency without raising active-period frequency. An empty population has no average, rather than a misleading zero average.

Scope and limits

Queries resolve tenant, application and environment on the server, require analytics.read and the analytics module, and return aggregates without visitor identifiers. Custom property filters require people.pii.read. Visitors use resolved person identity, then anonymous identity, then distinct identity; namespaces stay separate. Events without any identity are omitted.

Daily reports cover at most 90 days; weekly/monthly reports at most 366 days. Application retention applies immediately, including to historical classification. A consistent snapshot and 12-second statement budget bound each query. No sampling is applied. Late events, identity merges, deletion and retention changes can revise results; expired history cannot be reconstructed.

POST /api/v1/apps/{app}/analytics/engagement/query?range=30d&env=production
Authorization: Bearer <management-token>
Content-Type: application/json

{
  "version": 1,
  "period": "week",
  "event": "project_created",
  "filters": [{ "field": "device", "op": "eq", "value": "desktop" }]
}

The Management token needs read scope. The response includes the normalized definition, effective dates, retained-history start, cap flag, dense periods with completeness flags, completed-period summary totals, and both distributions with visitor counts and shares. new is the API field for First seen. Unavailable lifecycle counts are null; a complete period with no matching visitors has zero counts.

What the assistant can do here

Ask can run the engagement analysis for you and read the result: the lifecycle split, the frequency distributions and how they moved, for an action you describe in words rather than pick from a menu. It states the event filter it used, so you can tell whether "active" meant what you meant.

It cannot change what engagement means — the analysis is computed per question and nothing is stored — and it will not turn a lifecycle count into a claim about a CRM stage, which this module deliberately does not use.