---
title: "Find user keys by query"
method: GET
path: "/rest/api/2/user/search/query/key"
tags: ["User search"]
---

# Find user keys by query

`GET /rest/api/2/user/search/query/key`

Finds users with a structured query and returns a [paginated](#pagination) list of user keys.

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-2-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
- `maxResult` integer

## Response `200`

Returned if the request is successful.

- PageBeanUserKey — 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` UserKey[] — The list of items.
    - `accountId` string — The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. Returns *unknown* if the record is deleted and corrupted, for example, as the result of a server import.
    - `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.

## 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.dev/atlassian/apis/the-jira-cloud-platform-rest-api.md) · [All operations](https://skmtc.dev/atlassian/apis/the-jira-cloud-platform-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api/revisions/7e9af75061ea/schema)