Skip to main content

Get Cohort Processing State

Endpoint​

/o?method=cohortstate

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

Overview​

Retrieves the current processing state and status of a cohort. Shows whether cohort is actively recalculating, completed, or has errors. Useful for monitoring long-running cohort calculations.

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
cohortStringNoOptional; not used by current handler branch

Configuration Impact​

SettingDefaultAffectsUser-visible impact
cohorts.*Cohort feature defaultsCohort query/evaluation behavior used by this endpoint.Changes to cohort settings can affect result scope, calculation behavior, or filtering outcomes.
api.*Server API defaultsShared API execution controls (for example processing thresholds/limits).Changes to API-level controls can affect runtime behavior, limits, or response timing for this endpoint.

Response​

Success Response​

{
  "hashes": {
    "a4f...": {
      "data": {},
      "cid": ["cohort123"]
    }
  },
  "cohorts": {
    "cohort123": {
      "_id": "cohort123",
      "name": "High Value Users"
    }
  },
  "ts": 1739630000
}

Response Fields​

FieldTypeDescription
hashesObjectStep/signature map used for cohort membership evaluation.
cohortsObjectCohort definitions map keyed by cohort ID.
tsNumberCached snapshot timestamp (unix seconds).

Error Responses​

No explicit returnMessage(...) path in this branch.

Behavior/Processing​

  • Validates read permission for cohorts feature.
  • Returns the current cached cohort configuration from cohorts.getCurrentCohortConfig(...).
  • Output contains hash maps used by cohort processors plus cache timestamp metadata.

Notes​

  • This endpoint returns configuration/cache state, not a single cohort progress percentage.

Examples​

Example 1: Check cohort calculation state​

Request:

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

Database Collections​

CollectionUsed forData touched by this endpoint
countly.cohortsCollection:Source of state information

Limitations​

  • Does not show per-cohort progress percentage.
  • Returns snapshot-style config/cache state.

Database Collections​

  • countly.cohorts - Stores cohort processing state and status

Use Cases​

  1. Progress monitoring: Check if cohort is done recalculating
  2. Error checking: Identify why cohort calculation failed
  3. Scheduling: Determine when to fetch updated cohort data
  4. UI status: Show cohort state (loading/ready) in interface
  5. Health check: Verify cohort is in healthy state

Ⓔ 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