Get User Retention

Get user retention metrics for a date range.

Retention Definition:

• Session gap: 4 hours (14400 seconds)
• First event: Earliest timestamp for each user
• First return: First event occurring >= 4 hours after first event
• Days since first: (return_timestamp - first_event) / 86400

Retention Buckets:

• 1-day retention: Users who returned within 1 day of first event
• 7-day retention: Users who returned within 7 days of first event
• 30-day retention: Users who returned within 30 days of first event

Data Source:

• Calculated from users.data_tags array
• Supports both legacy (EVENTTYPE_timestamp) and new (EVENTTYPE|ISO) formats
• Only includes users with at least one event in the date range
• Ignores invalid timestamps (timestamp=0 or missing)

Query Parameters:

• start_date: ISO date string (YYYY-MM-DD), defaults to 30 days ago
• end_date: ISO date string (YYYY-MM-DD), defaults to today

Returns: Retention metrics: { "total_users": 1234, "avg_session_gap_hours": 48.5, "retention": [ {"days": 1, "count": 567, "percentage": 46}, {"days": 7, "count": 890, "percentage": 72}, {"days": 30, "count": 1100, "percentage": 89} ] }