Skip to main content

Get Specialized Cohort List

Endpoint​

/o?method=get_cohort_list

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

Overview​

Retrieves a filtered list of cohorts with advanced options for pagination, sorting, searching, and custom field projection. Provides efficient cohort discovery across large numbers of cohorts.

Authentication​

  • Authentication methods:
    • API Key (parameter): api_key=YOUR_API_KEY
    • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
    • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

Permissions​

  • Required permission: Read on the cohorts feature

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or auth_token)API key for authentication
auth_tokenStringYes (or api_key)Auth token for authentication
app_idStringYesApplication identifier
typeStringNoOptional cohort type filter (manual or auto)

Response​

Success Response​

{
  "a60e8cc976840453894a590575712351": "DocAuditTemp"
}

Response Fields​

FieldTypeDescription
<cohort_id>StringCohort name keyed by cohort ID

Error Responses​

HTTP StatusError ResponseDescription
400{"result": "Insufficient permissions"}User lacks Read permission

Behavior/Processing​

  • Validates read permission for cohorts feature.
  • Queries cohorts by app_id (and optional type).
  • Applies visibility filter and excludes names starting with [CLY]_.
  • Returns map object keyed by cohort ID with cohort name values.

Examples​

Example 1: Get a filtered cohort list​

Request:

curl -X GET "https://your-server.com/o?method=get_cohort_list" \
  -d "api_key=YOUR_API_KEY" \
  -d "app_id=YOUR_APP_ID" \
  -d "type=manual"

Database Collections​

CollectionUsed forData touched by this endpoint
countly.cohortsCollection:Source of cohort list
countly.cohortdataOptional Collection:Source of metrics if requested

Limitations​

  • Returns only _id -> name mapping, not full cohort documents.

Database Collections​

  • countly.cohorts - Stores cohort definitions and metadata

Use Cases​

  1. UI list display: Populate cohort selection dropdown with search
  2. Admin dashboard: Show paginated cohort list with sorting
  3. Bulk export: Export multiple cohorts with specific fields
  4. Cohort discovery: Find cohorts matching search criteria
  5. Analytics: Compare cohorts ranked by member count

Ⓔ Enterprise​

This feature is part of Countly Enterprise.

Get Access:

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

Last Updated​

2026-02-16