Skip to main content

Clean Up Unused Cohort Data

Endpoint​

/i/cohorts/cleanup

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

Overview​

Removes orphaned or unreferenced cohort data from the system. Performs maintenance on cohort metadata, user membership records, and aggregated data. Helps maintain database efficiency and removes traces of deleted 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: Update 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

Response​

Success Response​

{"result": "Started rechecking 1 apps"}

Response Fields​

FieldTypeDescription
resultStringAsync start message with app count

Error Responses​

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

Behavior/Processing​

  • Validates admin or manager authorization.
  • Starts asynchronous cleanup per matched app:
    • cleanupConditionalHashes
    • cleanupData
  • Immediate response is start message; detailed cleanup runs in background.

Cleanup Scope​

Operates only on specified app_id:

  • Does not affect other applications
  • Can be run multiple times safely

Examples​

Example 1: Clean up orphaned cohort data​

Request:

curl -X POST "https://your-server.com/i/cohorts/cleanup" \
  -d "api_key=YOUR_API_KEY" \
  -d "app_id=YOUR_APP_ID"

Database Collections​

CollectionUsed forData touched by this endpoint
countly.cohortUsersCollection:Removes orphaned membership records
countly.cohortdataCollection:Removes data for non-existent cohorts
countly.cohort_groupsCollection:Removes empty group definitions

Limitations​

  • Cleanup runs asynchronously in background after initial response.
  • Scope is app-specific when app_id is provided.

Database Collections​

  • countly.cohorts - Loads cohort definitions for cleanup logic
  • countly.cohortUsers - Cleans up cohort membership records

Use Cases​

  1. Maintenance routine: Regular cleanup after deleting many cohorts
  2. Performance optimization: Speed up queries by removing orphaned data
  3. Cache refresh: Clear stale cache after system issues
  4. Data integrity: Fix inconsistencies in cohort-user relationships
  5. Storage management: Reduce database size by removing unused data

Ⓔ 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