Groups

List groups

GET/groups
groups:readlist_groupsRead-only

Lists the groups your organisations can see, by name, one page at a time. A group is yours when its lead is a user of your organisations, or when it has no lead and one of its members is. Each group carries its lead, its parent, the number of your members and every feature flag. Search the name with filter[q]. Use GET /groups/{group_id}/members for the members of one group and GET /groups/{id} for one group.

Query parameters

  • limitinteger#

    Page size (1–100). Defaults to 25; values are clamped to the range.

    Default: 25
  • cursorstring#

    Opaque pagination cursor taken from a prior response's meta.next_cursor.

  • fieldsstring#

    Comma-separated top-level fields to return. id is always returned.

  • sortstring#

    Comma-separated fields to sort by: name or created_at. Prefix a field with - for descending. Defaults to name. The group id is always the final tiebreak.

  • filter[q]string#

    Groups whose name contains this text, ignoring case.

  • filter[parent_id]string (uuid)#

    Direct children of this group. Send filter[parent_id][null]=true for root groups. Takes [in] and [not_in] with a comma-separated list.

  • filter[lead_user_id]string (uuid)#

    Groups led by this user. Send filter[lead_user_id][null]=true for groups with no lead. Takes [in] and [not_in] with a comma-separated list.

  • filter[member_id]string (uuid)#

    Groups this user is a member of. The lead of a group is not one of its members. Takes [in] and [not_in] with a comma-separated list.

Responses

200

The groups.

Group[]
{
  "data": [
    {
      "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "name": "string",
      "description": "string",
      "lead_user_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "parent_id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
      "member_count": 1,
      "features": {
        "users_can_create_new_sub_groups": true,
        "can_be_invited_directly_to_group": true,
        "can_be_shown_in_sidebar": true,
        "user_auto_assign_to_classification": true,
        "can_invite_direct_investors": true
      },
      "created_at": "2026-06-12T10:00:00+00:00",
      "updated_at": "2026-06-12T10:00:00+00:00"
    }
  ],
  "meta": {
    "limit": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl https://your-org-domain/kong/core/api/v2/groups\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"