--- title: "Find users by query" method: GET path: "/rest/api/3/user/search/query" tags: ["User search"] --- # Find users by query `GET /rest/api/3/user/search/query` Finds users with a structured query and returns a [paginated](#pagination) list of user details. This operation takes the users in the range defined by `startAt` and `maxResults`, up to the thousandth user, and then returns only the users from that range that match the structured query. This means the operation usually returns fewer users than specified in `maxResults`. To get all the users who match the structured query, use [Get all users](#api-rest-api-3-users-search-get) and filter the records in your code. **[Permissions](#permissions) required:** *Browse users and groups* [global permission](https://confluence.atlassian.com/x/x4dKLg). The query statements are: * `is assignee of PROJ` Returns the users that are assignees of at least one issue in project *PROJ*. * `is assignee of (PROJ-1, PROJ-2)` Returns users that are assignees on the issues *PROJ-1* or *PROJ-2*. * `is reporter of (PROJ-1, PROJ-2)` Returns users that are reporters on the issues *PROJ-1* or *PROJ-2*. * `is watcher of (PROJ-1, PROJ-2)` Returns users that are watchers on the issues *PROJ-1* or *PROJ-2*. * `is voter of (PROJ-1, PROJ-2)` Returns users that are voters on the issues *PROJ-1* or *PROJ-2*. * `is commenter of (PROJ-1, PROJ-2)` Returns users that have posted a comment on the issues *PROJ-1* or *PROJ-2*. * `is transitioner of (PROJ-1, PROJ-2)` Returns users that have performed a transition on issues *PROJ-1* or *PROJ-2*. * `[propertyKey].entity.property.path is "property value"` Returns users with the entity property value. For example, if user property `location` is set to value `{"office": {"country": "AU", "city": "Sydney"}}`, then it's possible to use `[location].office.city is "Sydney"` to match the user. The list of issues can be extended as needed, as in *(PROJ-1, PROJ-2, ... PROJ-n)*. Statements can be combined using the `AND` and `OR` operators to form more complex queries. For example: `is assignee of PROJ AND [propertyKey].entity.property.path is "property value"` ## Query parameters - `query` string, required - `startAt` integer - `maxResults` integer ## Response `200` Returned if the request is successful. - PageBeanUser — A page of items. - `isLast` boolean — Whether this is the last page. - `maxResults` integer — The maximum number of items that could be returned. - `nextPage` string, uri — If there is another page of results, the URL of the next page. - `self` string, uri — The URL of the page. - `startAt` integer — The index of the first item returned. - `total` integer — The number of items returned. - `values` User[] — The list of items. - `accountId` string — The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. Required in requests. - `accountType` 'atlassian' | 'app' | 'customer' | 'unknown' — The user account type. Can take the following values: * `atlassian` regular Atlassian user account * `app` system account used for Connect applications and OAuth to represent external systems * `customer` Jira Service Desk account representing an external service desk - `active` boolean — Whether the user is active. - `appType` string — The app type of the user account when accountType is 'app'. Can take the following values: * `service` Service Account * `agent` Rovo Agent Account * `unknown` Unknown app type - `applicationRoles` SimpleListWrapperApplicationRole - `callback` ListWrapperCallbackApplicationRole - `items` ApplicationRole[] - `defaultGroups` string[] — The groups that are granted default access for this application role. As a group's name can change, use of `defaultGroupsDetails` is recommended to identify a groups. - `defaultGroupsDetails` GroupName[] — The groups that are granted default access for this application role. - `groupId` string, nullable — The ID of the group, which uniquely identifies the group across all Atlassian products. For example, *952d12c3-5b5b-4d04-bb32-44d383afc4b2*. - `name` string — The name of group. - `self` string, uri — The URL for these group details. - `defined` boolean — Deprecated. - `groupDetails` GroupName[] — The groups associated with the application role. - `groupId` string, nullable — The ID of the group, which uniquely identifies the group across all Atlassian products. For example, *952d12c3-5b5b-4d04-bb32-44d383afc4b2*. - `name` string — The name of group. - `self` string, uri — The URL for these group details. - `groups` string[] — The groups associated with the application role. As a group's name can change, use of `groupDetails` is recommended to identify a groups. - `hasUnlimitedSeats` boolean - `key` string — The key of the application role. - `name` string — The display name of the application role. - `numberOfSeats` integer — The maximum count of users on your license. - `platform` boolean — Indicates if the application role belongs to Jira platform (`jira-core`). - `remainingSeats` integer — The count of users remaining on your license. - `selectedByDefault` boolean — Determines whether this application role should be selected by default on user creation. - `userCount` integer — The number of users counting against your license. - `userCountDescription` string — The [type of users](https://confluence.atlassian.com/x/lRW3Ng) being counted against your license. - `max-results` integer - `pagingCallback` ListWrapperCallbackApplicationRole - `size` integer - `avatarUrls` AvatarUrlsBean - `16x16` string, uri — The URL of the item's 16x16 pixel avatar. - `24x24` string, uri — The URL of the item's 24x24 pixel avatar. - `32x32` string, uri — The URL of the item's 32x32 pixel avatar. - `48x48` string, uri — The URL of the item's 48x48 pixel avatar. - `displayName` string — The display name of the user. Depending on the user’s privacy setting, this may return an alternative value. - `emailAddress` string — The email address of the user. Depending on the user’s privacy setting, this may be returned as null. - `expand` string — Expand options that include additional user details in the response. - `groups` SimpleListWrapperGroupName - `callback` ListWrapperCallbackGroupName - `items` GroupName[] - `groupId` string, nullable — The ID of the group, which uniquely identifies the group across all Atlassian products. For example, *952d12c3-5b5b-4d04-bb32-44d383afc4b2*. - `name` string — The name of group. - `self` string, uri — The URL for these group details. - `max-results` integer - `pagingCallback` ListWrapperCallbackGroupName - `size` integer - `guest` boolean — Whether the user is a guest. - `key` string — This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. - `locale` string — The locale of the user. Depending on the user’s privacy setting, this may be returned as null. - `name` string — This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. - `self` string, uri — The URL of the user. - `timeZone` string — The time zone specified in the user's profile. If the user's time zone is not visible to the current user (due to user's profile setting), or if a time zone has not been set, the instance's default time zone will be returned. ## Other responses - `400` — Returned if the query is invalid. - `401` — Returned if the authentication credentials are incorrect or missing. - `403` — Returned if the user does not have the necessary permission. - `408` — Returned if the search is timed out. --- [API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/versions/ec7f275dfee5/schema)