Skip to main content

List Groups

Endpoint​

/o/groups

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

Overview​

Returns all groups with computed member counts.

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 access: global admin

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or auth_token)API key authentication
auth_tokenStringYes (or api_key)Auth token authentication

Response​

Success Response​

{
  "result": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Marketing Team",
      "groupID": "marketing-team",
      "global_admin": false,
      "permission": {
        "_": { "u": [], "a": [] },
        "c": {},
        "r": {},
        "u": {},
        "d": {}
      },
      "users": ["507f191e810c19729de860ea"],
      "matched_users_count": 1
    }
  ]
}

Response Fields​

FieldTypeDescription
resultArrayList of group documents
result[].matched_users_countNumberComputed user count via lookup on members
result[].usersArrayGroup member IDs

Error Responses​

HTTP StatusResponse
400{ "result": "Missing parameter \"api_key\" or \"auth_token\"" }
400Error object from database read path

Behavior/Processing​

  1. Loads groups from countly.groups.
  2. Performs lookup into countly.members to compute matched_users_count.
  3. Returns groups as { "result": [...] }.

Database Collections​

CollectionUsed forData touched by this endpoint
countly.groupsEndpoint data source** - Primary source collection
countly.membersEndpoint data source** - Lookup source for matched_users_count

Examples​

Example: List all groups​

https://your-server.com/o/groups?api_key=YOUR_API_KEY

Ⓔ 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