userGroup/getMany

Retrieve a list of all User Groups in the Slack workspace. Returns group IDs, handles, names, descriptions, and member counts. Optionally includes disabled groups.

When to Use

List all active groups for a directory or admin dashboard.
Audit group memberships and sizes across the workspace for governance reporting.
Find a group by handle before updating its membership — use the handle to look up the userGroupId.
Populate a group picker UI element in a custom Slack app or admin tool.
Generate a report of all groups (including disabled) to identify stale groups that should be cleaned up.

Configuration

Connection

Field	Required	Description
`botToken`	Required	Slack Bot Token starting with `xoxb-`. Requires the `usergroups:read` OAuth scope.

Operation Fields

Field	Required	Description
`includeDisabled`	Optional	Boolean. Default `true`. When `true`, includes disabled groups in the response. Set to `false` to return only active groups.
`includeCount`	Optional	Boolean. Default `true`. When `true`, includes the member count (`userCount`) for each group. Set to `false` for slightly faster responses when count is not needed.

Sample Configuration

{
  "operation": "userGroup/getMany",
  "connection": {
    "botToken": "{{ $credentials.slackBot.token }}"
  },
  "includeDisabled": false,
  "includeCount": true
}

Validation Errors

Error Code	Cause	Resolution
`missing_scope`	Token lacks the `usergroups:read` scope.	Add `usergroups:read` under OAuth & Permissions and reinstall the app.
`invalid_auth`	Bot token is invalid or revoked.	Regenerate the token and update the credential store.

Output

Success Port

Field	Type	Description
`userGroupCount`	number	Total number of groups returned in this result set.
`userGroups`	array	Array of group objects. Each entry contains: `userGroupId`, `handle`, `name`, `description`, `userCount` (if `includeCount` is true).
`status`	string	`"success"` on successful retrieval.
`errorCode`	string	Empty on success. Slack API error code on failure.
`payload`	object	Raw Slack API response for advanced field access.

Error Port

Activated when the token lacks the required scope or is invalid.

Sample Output

{
  "userGroupCount": 3,
  "userGroups": [
    {
      "userGroupId": "S08ONCALL01",
      "handle": "platform-oncall",
      "name": "Platform On-Call",
      "description": "Current on-call rotation for the Platform team",
      "userCount": 3
    },
    {
      "userGroupId": "S08FRONTEND",
      "handle": "frontend-team",
      "name": "Frontend Team",
      "description": "All frontend engineers",
      "userCount": 8
    },
    {
      "userGroupId": "S08INTERNS1",
      "handle": "summer-interns",
      "name": "Summer Interns",
      "description": "2026 summer intern cohort",
      "userCount": 12
    }
  ],
  "status": "success",
  "errorCode": "",
  "payload": {
    "ok": true
  }
}

Expression Reference

Expression	Result
`{{ $output.getManyGroups.userGroupCount }}`	Total number of groups returned — for summary reporting.
`{{ $output.getManyGroups.userGroups }}`	Full groups array for iteration or filtering.
`{{ $output.getManyGroups.userGroups[0].userGroupId }}`	First group's ID — pass to membership or update operations.
`{{ $output.getManyGroups.userGroups[0].handle }}`	First group's handle for display or lookup.
`{{ $output.getManyGroups.userGroups[0].userCount }}`	Member count for the first group — useful for capacity reporting.

Node Policies & GuardRails

Policy Area	Recommendation
Disabled Group Inclusion	Set `includeDisabled: true` (the default) when you need to find group IDs for re-enable or cleanup operations. Set to `false` for active-only directory views.
Handle-Based Lookup	Use `userGroup/getMany` to perform a handle-to-ID lookup before calling update, disable, or membership operations. Hardcoding group IDs is fragile — handles are more stable.
Count Overhead	Requesting `includeCount: true` adds a slight overhead for large workspaces. Omit it when building lists where member counts are not needed.
Result Size	The API returns all groups in a single response (no pagination). For workspaces with many groups, the payload may be large. Process inline and avoid holding the full array in memory.
Caching	Group lists change infrequently. Cache results for 5–15 minutes in high-frequency workflows that repeatedly look up group IDs by handle.

Examples

Find Group ID by Handle for Membership Update

Before updating on-call rotation, find the @platform-oncall group ID to pass to userGroup/addUsers.

{
  "operation": "userGroup/getMany",
  "includeDisabled": false,
  "includeCount": false
}
// Filter: userGroups.find(g => g.handle === 'platform-oncall')?.userGroupId

Generate Group Size Report

Retrieve all active groups with member counts for a weekly workspace governance report.

{
  "operation": "userGroup/getMany",
  "includeDisabled": false,
  "includeCount": true
}
// Iterate userGroups to build: { handle, name, userCount } report

Audit All Groups Including Disabled

List all groups — active and disabled — to identify stale groups that should be cleaned up.

{
  "operation": "userGroup/getMany",
  "includeDisabled": true,
  "includeCount": true
}
// Flag groups where userCount === 0 or that have not been active recently