Retention

Analytics → Retention measures whether visitors who perform a starting action return to perform another action. Open Edit retention, select events and filters, choose daily/weekly/monthly cohorts, then Run retention. The URL preserves the definition, date range and environment.

Read the grid

Summary rates combine completed periods, weighted by cohort size. Zero-return cohorts remain in the denominator. Segment comparison shows the exact returned/eligible counts; overlapping segment totals should not be added.

Define entry and return

• First matching start: each visitor enters once, at their first matching event in retained history. An earlier matching start outside the selected range prevents re-entry. This is not an all-time first visit when older events have expired.
• Every period with a start: a visitor joins once in each calendar period where they perform the start action. The first matching event in that period determines entry and segment membership.
• Start and return actions each accept an exact event name and up to five filters. An empty name means any event. Filters support standard fields or property.<name>; custom properties require people.pii.read.
• Up to three named segments filter properties on the selected entry event. Later changes do not change membership. Return filters apply to return events independently.

Returns count at or after the entry timestamp. The start itself counts if it matches the return condition; otherwise period 0 can be below 100%. Each visitor counts at most once per cohort/return period. Weeks begin Monday; all buckets use the application timezone, including daylight-saving changes. Identity follows the stored person, anonymous ID or distinct ID, with separate namespaces.

Limits

Daily reports cover up to 90 days and display 31 return periods. Weekly/monthly reports cover up to 366 days and display 53/13 periods respectively. Application retention applies immediately, even before physical cleanup. First-entry detection searches retained history. Queries run in a consistent read-only snapshot with a 12-second statement budget; timeouts ask for a shorter range or specific start event.

Late events, identity merges, deletion and retention can change historical results. Ephemeral identity cannot establish cross-visit retention. No definition or raw visitor identifier is stored by this report.

Management API

GET /api/v1/apps/{app}/analytics/retention?cohortBy=day&startEvent=signup&event=purchase&mode=first&range=30d&env=production

Existing filter=dimension:value parameters remain supported and filter both starts and returns; they limit the window to 90 days. Existing cohorts[].periods remain unique visitor counts. Each row additionally exposes complete[] and partial; use only completed cells for summary denominators.

For action filters and segment comparisons, send a read-only query with a Management token that has read scope and analytics.read:

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

{
  "version": 1,
  "cohortBy": "day",
  "mode": "first",
  "start": { "event": "signup", "filters": [] },
  "returning": { "event": "purchase", "filters": [] },
  "segments": [
    { "key": "A", "label": "All signups", "filters": [] },
    { "key": "B", "label": "Mobile", "filters": [
      { "field": "device", "op": "eq", "value": "mobile" }
    ] }
  ]
}

The response includes each segment's cohorts, the first segment as cohorts for compatibility, the normalized definition, effective from/to, historyFrom, capped, timezone and periodLimit. The MCP get_retention tool supports start/return names, grain and entry mode. Use the Management API for advanced segment definitions.

What the assistant can do here

Ask reads cohorts: weekly or monthly retention for an action you describe, the curve, and how one cohort compares with another. It states the cohort definition and the range it used, because a retention number without its definition is not an answer.

Retention has no stored configuration of its own, so nothing in this module needs an approval — every question here is answered on the spot.