Cohorts API Documentation

Enterprise

This feature is part of Countly Enterprise. To get access, contact sales or compare versions. Existing customers can reach the support portal with questions.

Overview

The Cohorts feature provides behavior-based and property-based user segmentation. It supports:

• Auto cohorts (generated from steps and/or user segmentation rules)
• Manual cohorts (profile groups managed by explicit add/remove operations)

Cohorts are used for analytics segmentation, targeting workflows, and cohort comparison widgets.

Quick Links

Read Endpoints (/o)

Endpoint	Purpose
get_cohorts	List cohorts with filtering, pagination, and visibility controls
get_cohort	Read one cohort with creator/group metadata
cohortstate	Read current cohort processing state
cohortdata	Read cohort time-series/user data
get_cohort_list	Read compact cohort name map
get_cohort_metrics	Read calculated cohort metrics

Write Endpoints (/i/cohorts)

Endpoint	Purpose
add	Create cohort or profile group
edit	Update cohort fields
delete	Delete one or multiple cohorts
add_users	Add users to manual cohort
remove_users	Remove users from manual cohort
group	Update cohort grouping metadata
recalculate	Trigger recalculation for a cohort
detail_metrics	Update detail metrics fields
resetRealTimeData	Reset real-time cohort data
cleanup	Cleanup cohort-related data
fixuid	Fix missing u_id references

Configuration & Behavior

Feature config scope: cohorts

• regenerate_interval (default 3600): periodic regeneration interval in seconds
• realtime_cohorts (default true): controls real-time update behavior

Behavior summary:

• realtime_cohorts=true: non-manual cohorts are kept in real-time update flow.
• realtime_cohorts=false: non-manual cohorts are recalculated by regeneration/scheduled flow and manual recalculation triggers.

Workflow Examples

Dynamic Cohort Lifecycle

1. Create cohort with steps or user segmentation via add.
2. Check processing state with cohortstate.
3. Read list/detail/data via get_cohorts, get_cohort, and cohortdata.
4. Edit logic with edit and recalculate if needed via recalculate.

Manual Profile Group Lifecycle

1. Create with type=manual via add.
2. Add users via add_users from query/uids/file/text.
3. Remove users via remove_users.
4. Group/organize or delete when no longer needed.

Related Features

• Drill (cohort queries and drill metadata)
• Users / App Users (membership and user profile resolution)
• Dashboards (cohort widget data and cleanup)
• Tasks / Long-running jobs (bulk add/remove and heavy recalculations)

Implementation details

Database Collections

• countly.cohorts: cohort definitions, ownership, visibility, grouping, configuration
• countly.cohortUsers: cohort membership records (especially manual/profile groups)
• countly.cohortdata: cohort data metrics used by cohort data reads
• countly.profile_groups_imports: async import jobs for add-users operations
• countly.app_users{app_id}: user-level cohort hash/state updates
• countly.members: creator lookup for detailed cohort reads
• countly.systemlogs: audit records for edit/delete and user add/remove actions
• countly_drill.cohort_meta: drill-side cohort meta used by real-time/reset flows
• countly_drill.drill_meta{app_id} and countly_drill.drill_meta: drill metadata touched during reset/cleanup paths