Get cohort-based user retention analytics (Admin only)

Request

Returns cohort retention data showing how user cohorts perform over time. Each cohort represents users who joined in a specific month, tracked across subsequent months. Replaces 13 separate API calls with 1 efficient query. Industry-standard cohort analysis for retention heatmaps. Requires admin authentication.

Security

authJWT

Bodyapplication/jsonrequired

User retention analytics request with monthsBack and filters

startMonthstring, (date-time)

Starting month for retention analysis (defaults to current month)

Example:"2026-02-01T00:00:00Z"

monthsBacknumber, [ 1 .. 24 ]

Number of months to analyze (looking backwards)

Default:13

Example:13

filtersobject(RetentionAnalyticsFiltersDTO)

Optional filters for retention query

curl -i -X POST \
  https://docs.pers.ninja/_mock/swagger/analytics/users/retention \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "monthsBack": 13
  }'

Responses

Cohort retention analytics successfully retrieved

Bodyapplication/json

resultsArray of objects(RetentionMonthResultDTO)required

Array of monthly retention results (ordered chronologically)

totalMonthsnumberrequired

Total number of months analyzed

Example:13

metadataobjectrequired

Query metadata

Response

{
  "results": [
    { … }
  ],
  "totalMonths": 13,
  "metadata": {}
}