---
title: "Find groups"
method: GET
path: "/rest/api/2/groups/picker"
tags: ["Groups"]
---

# Find groups

`GET /rest/api/2/groups/picker`

Returns a list of groups whose names contain a query string. A list of group names can be provided to exclude groups from the results.

The primary use case for this resource is to populate a group picker suggestions list. To this end, the returned object includes the `html` field where the matched query term is highlighted in the group name with the HTML strong tag. Also, the groups list is wrapped in a response object that contains a header for use in the picker, specifically *Showing X of Y matching groups*.

The list returns with the groups sorted. If no groups match the list criteria, an empty list is returned.

This operation can be accessed anonymously.

**[Permissions](#permissions) required:** *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg). Anonymous calls and calls by users without the required permission return an empty list.

*Browse users and groups* [global permission](https://confluence.atlassian.com/x/x4dKLg). Without this permission, calls where query is not an exact match to an existing group will return an empty list.

## Query parameters

- `accountId` string
- `query` string
- `exclude` string[]
- `excludeId` string[]
- `maxResults` integer
- `caseInsensitive` boolean
- `userName` string

## Response `200`

Returned if the request is successful.

- FoundGroups — The list of groups found in a search, including header text (Showing X of Y matching groups) and total of matched groups.
  - `groups` FoundGroup[]
    - `avatarUrl` string — Avatar url for the group/team if present.
    - `groupId` string — The ID of the group, which uniquely identifies the group across all Atlassian products. For example, *952d12c3-5b5b-4d04-bb32-44d383afc4b2*.
    - `html` string — The group name with the matched query string highlighted with the HTML bold tag.
    - `labels` GroupLabel[]
      - `text` string — The group label name.
      - `title` string — The title of the group label.
      - `type` 'ADMIN' | 'SINGLE' | 'MULTIPLE' — The type of the group label.
    - `managedBy` 'EXTERNAL' | 'ADMINS' | 'TEAM_MEMBERS' | 'OPEN' — Describes who/how the team is managed. The possible values are \* external - when team is synced from an external directory like SCIM or HRIS, and team members cannot be modified. \* admins - when a team is managed by an admin (team members can only be modified by admins). \* team-members - managed by existing team members, new members need to be invited to join. \* open - anyone can join or modify this team.
    - `name` string — The name of the group. The name of a group is mutable, to reliably identify a group use ``groupId`.`
    - `usageType` 'USERBASE_GROUP' | 'TEAM_COLLABORATION' | 'ADMIN_OVERSIGHT' — Describes the type of group. The possible values are \* team-collaboration - A platform team managed in people directory. \* userbase-group - a group of users created in adminhub. \* admin-oversight - currently unused.
  - `header` string — Header text indicating the number of groups in the response and the total number of groups found in the search.
  - `total` integer — The total number of groups found in the search.

---

[API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api/versions/a26541c2f8bd/schema)