Cohorts API Documentation

Ⓔ Enterprise Only
This feature is available exclusively in Countly Enterprise.

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.

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

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)

---

Ⓔ Enterprise

This feature is part of Countly Enterprise.

Get Access:

• Learn about Enterprise
• Contact Sales
• Compare Versions

Already a Customer? Use support portal if you have any questions.

---

Last Updated: 2026-02-15