6 min de leitura

GET /retention/:websiteId

Retrieve cohort-based retention analysis for your website. Returns retention rates for visitor cohorts grouped by their first visit date, showing how many visitors return in subsequent time periods.

GET/api/external/v1/retention/:websiteId

Get cohort-based retention analysis

Authentication

All requests require an API key passed via the X-API-Key header. Alternatively, you can use the Authorization: Bearer YOUR_API_KEY header.

AuthenticationBash

curl -X GET 'https://api.zenovay.com/api/external/v1/retention/a1b2c3d4-e5f6-7890-abcd-ef1234567890?range=30d&granularity=weekly' \
-H 'X-API-Key: YOUR_API_KEY'

This endpoint requires a Pro plan or higher. Free-tier API keys will receive a 403 Forbidden response.

Credit Cost

Each request to this endpoint costs 1 API credit.

Parameters

Name	Type	Required	Default	Description
`websiteId`	string (path)	Yes	-	The UUID of the website
`range`	string (query)	No	`30d`	Time range: `24h`, `7d`, `30d`, `90d`
`granularity`	string (query)	No	`weekly`	Cohort granularity: `daily`, `weekly`, `monthly`
`periods`	integer (query)	No	`6`	Number of retention periods to track (1-12)

Response

Response (200 OK)JSON

{
"success": true,
"data": {
  "cohorts": [
    {
      "cohort_date": "2026-02-17",
      "period_number": 0,
      "total_users": 1243,
      "retained_users": 1243,
      "retention_rate": 100.0
    },
    {
      "cohort_date": "2026-02-17",
      "period_number": 1,
      "total_users": 1243,
      "retained_users": 534,
      "retention_rate": 42.96
    },
    {
      "cohort_date": "2026-02-17",
      "period_number": 2,
      "total_users": 1243,
      "retained_users": 312,
      "retention_rate": 25.10
    },
    {
      "cohort_date": "2026-02-17",
      "period_number": 3,
      "total_users": 1243,
      "retained_users": 198,
      "retention_rate": 15.93
    },
    {
      "cohort_date": "2026-02-24",
      "period_number": 0,
      "total_users": 1087,
      "retained_users": 1087,
      "retention_rate": 100.0
    },
    {
      "cohort_date": "2026-02-24",
      "period_number": 1,
      "total_users": 1087,
      "retained_users": 489,
      "retention_rate": 44.99
    },
    {
      "cohort_date": "2026-02-24",
      "period_number": 2,
      "total_users": 1087,
      "retained_users": 276,
      "retention_rate": 25.39
    },
    {
      "cohort_date": "2026-03-03",
      "period_number": 0,
      "total_users": 1356,
      "retained_users": 1356,
      "retention_rate": 100.0
    },
    {
      "cohort_date": "2026-03-03",
      "period_number": 1,
      "total_users": 1356,
      "retained_users": 612,
      "retention_rate": 45.13
    }
  ],
  "summary": {
    "overall_retention": 38.4,
    "total_cohorts": 3,
    "best_cohort": {
      "cohort_date": "2026-03-03",
      "retention_rate": 45.13
    }
  }
},
"timestamp": "2026-03-16T15:00:00.000Z"
}

Response Fields

Field	Type	Description
`cohorts`	array	List of cohort retention records
`cohorts[].cohort_date`	string	Start date of the cohort (YYYY-MM-DD)
`cohorts[].period_number`	number	The retention period (0 = initial visit, 1 = first return period, etc.)
`cohorts[].total_users`	number	Total number of users in the cohort
`cohorts[].retained_users`	number	Number of users who returned in this period
`cohorts[].retention_rate`	number	Percentage of users retained (0-100)
`summary.overall_retention`	number	Average period-1 retention rate across all cohorts
`summary.total_cohorts`	number	Total number of cohorts in the analysis
`summary.best_cohort.cohort_date`	string	Start date of the best-performing cohort
`summary.best_cohort.retention_rate`	number	Period-1 retention rate of the best cohort

Understanding Cohort Data

The response returns a flat array of cohort-period pairs. To build a retention heatmap, group records by cohort_date and use period_number as columns:

Cohort	Period 0	Period 1	Period 2	Period 3
Feb 17	100%	42.96%	25.10%	15.93%
Feb 24	100%	44.99%	25.39%	-
Mar 3	100%	45.13%	-	-

TypeScript Interface

RetentionResponseTypeScript

interface CohortRecord {
cohort_date: string;
period_number: number;
total_users: number;
retained_users: number;
retention_rate: number;
}

interface RetentionResponse {
success: true;
data: {
  cohorts: CohortRecord[];
  summary: {
    overall_retention: number;
    total_cohorts: number;
    best_cohort: {
      cohort_date: string;
      retention_rate: number;
    };
  };
};
timestamp: string;
}

HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters (e.g. periods > 12)
401	Unauthorized - Invalid or missing API key
403	Forbidden - Pro plan or higher required
404	Not Found - Website not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Code Examples

cURLBash

curl -X GET 'https://api.zenovay.com/api/external/v1/retention/a1b2c3d4-e5f6-7890-abcd-ef1234567890?range=30d&granularity=weekly&periods=6' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json'

Error Handling

Error Response (403 Forbidden)JSON

{
"success": false,
"error": {
  "message": "This endpoint requires a Pro plan or higher",
  "code": "PLAN_REQUIRED",
  "timestamp": "2026-03-16T15:00:00.000Z"
}
}