Cohort Analytics (V2)

Cohorts (V2)

Single report contract for retention, churn, comparison snapshot, and diagnostics.

Audience: Lifecycle and product analysts who need a clear retention + churn view in one call.

Critical: Breaking change: legacy comparison/churn endpoints are removed. Use only /api/v1/analytics/cohort/:siteId.

OverviewFunnelsJourneys

Breaking Change

• Removed: GET /api/v1/analytics/cohort/:siteId/comparison
• Removed: GET /api/v1/analytics/cohort/:siteId/churn
• Removed: POST /api/v1/analytics/cohort/:siteId/cache/refresh
• Removed: POST /api/v1/analytics/cohort/:siteId/cache/invalidate
• New: POST /api/v1/analytics/cohort/:siteId/cache/rebuild
• Unified response: meta, summary, retention, churn, comparison, diagnostics

Quick Start (2-5 Minutes)

1

Load cohort report

Get retention, churn, comparison snapshot, diagnostics in one response.

GET /api/v1/analytics/cohort/:siteId?cohortType=first_visit&intervalType=day&startDate=2026-01-01&endDate=2026-01-31&periodCount=12

2

Export the same report

Download CSV or JSON with the same required filters.

GET /api/v1/analytics/cohort/:siteId/export?cohortType=first_visit&intervalType=day&startDate=2026-01-01&endDate=2026-01-31&periodCount=12&format=csv

3

Rebuild cache for one report key

Clear site-level cohort V2 cache and warm selected filters.

POST /api/v1/analytics/cohort/:siteId/cache/rebuild?cohortType=first_visit&intervalType=day&startDate=2026-01-01&endDate=2026-01-31&periodCount=12

Cohort V2 endpoints

GET  /api/v1/analytics/cohort/:siteId
GET  /api/v1/analytics/cohort/:siteId/export
POST /api/v1/analytics/cohort/:siteId/cache/rebuild

Required Query Fields

Field	Required	Type	Used by events	Description
siteId	Required	uuid	all cohort V2 endpoints	Target site scope.
cohortType	Required	signup | first_purchase | first_visit	report/export/rebuild	Defines cohort start event.
intervalType	Required	day | week | month	report/export/rebuild	Retention and churn bucket size.
startDate	Required	ISO date string	report/export/rebuild	Inclusive report window start.
endDate	Required	ISO date string	report/export/rebuild	Inclusive report window end.
periodCount	Required	number (1-24)	report/export/rebuild	Retention columns as P0..Pn.
format	Required for export	csv | json	export	Download format.

Response Contract (V2)

• meta: site, filters, generatedAt, cache key/status.
• summary: totalUsers, cohortCount, activePeriodCount, overallRetentionRate, overallChurnRate.
• retention: columns (P0..Pn) and row-level retainedUsers/retentionRate.
• churn: period series with newUsers, returningUsers, churnedUsers, churnRate, isActivePeriod.
• comparison: snapshot columns (P0..P6) for side-by-side cohort scan.
• diagnostics: reason code + message + recommended actions.

Decision Matrix

Scenario	Use This	Why
Need full cohort analytics page payload	/analytics/cohort/:siteId	Single source for retention + churn + diagnostics.
Need offline analysis in BI tools	/analytics/cohort/:siteId/export	CSV/JSON export with same filters.
Need stale cache recovery	/analytics/cohort/:siteId/cache/rebuild	Clears cohort V2 cache and warms selected key.

Troubleshooting

Diagnostics shows NO_EVENTS_IN_RANGE

Cause: No tracked activity in selected dates.

Fix: Widen date range or verify tracking deployment for this site.

Diagnostics shows NO_COHORT_EVENTS_FOR_TYPE

Cause: Selected cohort starter event is not present.

Fix: Switch cohortType or validate event names and visitorId coverage.

Rows look empty

Cause: Periods have not elapsed yet (future cells).

Fix: Use shorter periodCount or older date window for complete columns.

Production Checklist

• Clients use only cohort V2 endpoints (legacy endpoints removed).Required
• UI explains P0/P1 semantics and next-period churn definition.Required
• Cache rebuild endpoint is available for operations.Required
• Monitoring tracks diagnostics reason code distribution.Required

Next Steps

• Overview
• Funnels
• Journeys