Skip to main content

/o/app_users/loyalty

Endpoint​

/o/app_users/loyalty

Overview​

Return loyalty distribution buckets for all-time, last 7 days, and last 30 days.

Authentication​

  • 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​

  • Requires read-level app access.

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or use auth_token)Dashboard API authentication key.
auth_tokenStringYes (or use api_key)Dashboard auth token.
app_idStringYesTarget app ID.
queryJSON String (Object)NoOptional filter query applied before loyalty bucket aggregation.

Response​

Success Response​

{
  "all": [
    {"_id":"1","count":120,"index":0},
    {"_id":"2","count":43,"index":1},
    {"_id":"3-5","count":98,"index":2}
  ],
  "7days": [
    {"_id":"1","count":21,"index":0}
  ],
  "30days": [
    {"_id":"1","count":50,"index":0}
  ]
}

Aggregation-fallback shape (still HTTP 200):

{}

Response Fields​

FieldTypeDescription
allArray of ObjectsLoyalty distribution across all matched users.
7daysArray of ObjectsLoyalty distribution for users active in last 7 days.
30daysArray of ObjectsLoyalty distribution for users active in last 30 days.
bucket._idStringBucket label (1, 2, 3-5, 6-9, 10-19, 20-49, 50-99, 100-499, 500+).
bucket.countNumberUser count in bucket.
bucket.indexNumberStable sort index for bucket ordering.

Error Responses​

Status Code: 400 Bad Request

{
  "result": "Missing parameter \"app_id\""
}

Behavior/Processing​

Behavior Modes​

ModeTriggerProcessing PathResponse Shape
Query parsedquery is valid JSON (or omitted)Applies preprocessors and aggregates loyalty ranges for all, 7-day, and 30-day windows.Raw object: { "all": [...], "7days": [...], "30days": [...] }
Query parse fallbackquery JSON parsing failsFalls back to empty query {} and runs aggregation on full app-user scope.Raw object: { "all": [...], "7days": [...], "30days": [...] }
Aggregation errorAny aggregation promise failsReturns empty raw object.Raw object: {}

Query Enrichment​

  • If Cohorts is enabled, cohort filters in query are preprocessed and merged before aggregation.
  • This can change which users are included in loyalty buckets even when the raw query payload is unchanged.

Database Collections​

CollectionUsed forData touched by this endpoint
countly.membersAuthentication and permission validationReads member identity and app-level read permissions.
countly.app_users{appId}Loyalty aggregation sourceReads sc (session count), ls (last seen), and filter-matched user fields to build loyalty buckets.

Examples​

Example 1: Loyalty distribution​

/o/app_users/loyalty?api_key=YOUR_API_KEY&app_id=64b0ac10c2c3ce0012dd1001
{
  "all": [
    {"_id":"1","count":120,"index":0}
  ],
  "7days": [],
  "30days": []
}

Limitations​

  • Query parse failures silently fall back to {} filter.

Last Updated​

2026-02-17