elasticsearch/docs/reference/rest-api/security/query-user.asciidoc

[role="xpack"]
[[security-api-query-user]]
=== Query User API

++++
<titleabbrev>Query User</titleabbrev>
++++

Retrieves <<native-realm,native users>> with <<query-dsl,Query DSL>> in a <<paginate-search-results,paginated>> fashion.

NOTE: As opposed to the <<security-api-get-user,get user api>>, <<built-in-users,built-in users>> are excluded from the
result. This API is only for <<native-realm,native users>>.

[[security-api-query-user-request]]
==== {api-request-title}

`GET /_security/_query/user`

`POST /_security/_query/user`

[[security-api-query-user-prereqs]]
==== {api-prereq-title}

* To use this API, you must have at least the  `read_security` cluster privilege.

[[security-api-query-user-desc]]
==== {api-description-title}

Use this API to retrieve users managed by the
<<native-realm,native realm>> in a paginated manner.
You can optionally filter the results with a query.

[[security-api-query-user-request-body]]
==== {api-request-body-title}

You can specify the following parameters in the request body:

`query`::
(Optional, string) A <<query-dsl,query>> to filter which users to return.
The query supports a subset of query types, including
<<query-dsl-match-all-query,`match_all`>>, <<query-dsl-bool-query,`bool`>>,
<<query-dsl-term-query,`term`>>, <<query-dsl-terms-query,`terms`>>,
<<query-dsl-match-query,`match`>>, <<query-dsl-ids-query,`ids`>>,
<<query-dsl-prefix-query,`prefix`>>, <<query-dsl-wildcard-query,`wildcard`>>,
<<query-dsl-exists-query,`exists`>>, <<query-dsl-range-query,`range`>>,
and <<query-dsl-simple-query-string-query,`simple query string`>>.
+
You can query the following public values associated with a user.
+
.Valid values for `query`
[%collapsible%open]
====
`username`::
An identifier for the user.

`roles`::
An array of the role names of the <<defining-roles, roles>> that are assigned to the user.

`full_name`::
Full name of the user.

`email`::
The email of the user.

`enabled`::
Specifies whether the user is enabled.
====

include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=from]
+
By default, you cannot page through more than 10,000 hits using the `from` and
`size` parameters. To page through more hits, use the
<<search-after,`search_after`>> parameter.

`size`::
(Optional, integer) The number of hits to return. Must not be negative and defaults to `10`.
+
By default, you cannot page through more than 10,000 hits using the `from` and
`size` parameters. To page through more hits, use the
<<search-after,`search_after`>> parameter.

`sort`::
(Optional, object) <<sort-search-results,Sort definition>>. You can sort on `username`, `roles` or `enabled`.
In addition, sort can also be applied to the `_doc` field to sort by index order.

`search_after`::
(Optional, array) <<search-after,Search after>> definition.

[[security-api-query-user-query-params]]
==== {api-query-parms-title}

`with_profile_uid`::
(Optional, boolean) Determines whether to retrieve the <<user-profile,user profile>> `uid`,
if exists, for the users. Defaults to `false`.

[[security-api-query-user-response-body]]
==== {api-response-body-title}

This API returns the following top level fields:

`total`::
The total number of users found.

`count`::
The number of users returned in the response.

`users`::
A list of users that match the query.

[[security-api-query-user-example]]
==== {api-examples-title}

The following request lists all users, assuming you have the
`read_security` privilege:

[source,console]
----
GET /_security/_query/user
----
// TEST[setup:jacknich_user,sandrakn_user]

A successful call returns a JSON structure that contains the information
retrieved from one or more users:

[source,console-result]
----
{
    "total": 2,
    "count": 2,
    "users": [ <1>
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "jacknich@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        },
        {
            "username": "sandrakn",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Sandra Knight",
            "email": "sandrakn@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        }
    ]
}
----
// NOTCONSOLE

<1> The list of users that were retrieved for this request

If you create a user with the following details:

[source,console]
----
POST /_security/user/jacknich
{
  "password" : "l0ng-r4nd0m-p@ssw0rd",
  "roles" : [ "admin", "other_role1" ],
  "full_name" : "Jack Nicholson",
  "email" : "jacknich@example.com",
  "metadata" : {
    "intelligence" : 7
  }
}
----

A successful call returns a JSON structure:

[source,console-result]
----
{
  "created": true
}
----

Use the user information retrieve the user with a query:

[source,console]
----
POST /_security/_query/user
{
    "query": {
        "prefix": {
            "roles": "other"
        }
    }
}
----
// TEST[setup:jacknich_user]
A successful call returns a JSON structure for a user:

[source,console-result]
--------------------------------------------------
{
    "total": 1,
    "count": 1,
    "users": [
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "jacknich@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        }
    ]
}
--------------------------------------------------
// NOTCONSOLE

To retrieve the user `profile_uid` as part of the response:

[source,console]
--------------------------------------------------
POST /_security/_query/user?with_profile_uid=true
{
    "query": {
        "prefix": {
            "roles": "other"
        }
    }
}
--------------------------------------------------
// TEST[setup:jacknich_user]

[source,console-result]
--------------------------------------------------
{
    "total": 1,
    "count": 1,
    "users": [
        {
            "username": "jacknich",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Jack Nicholson",
            "email": "jacknich@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "profile_uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
        }
    ]
}
--------------------------------------------------
// NOTCONSOLE

Use a `bool` query to issue complex logical conditions and use
`from`, `size`, `sort` to help paginate the result:

[source,js]
----
POST /_security/_query/user
{
  "query": {
    "bool": {
      "must": [
        {
          "wildcard": {
            "email": "*example.com" <1>
          }
        },
        {
          "term": {
            "enabled": true <2>
          }
        }
      ],
      "filter": [
        {
          "wildcard": {
            "roles": "*other*" <3>
          }
        }
      ]
    }
  },
  "from": 1, <4>
  "size": 2, <5>
  "sort": [
    { "username": { "order": "desc"} } <6>
  ]
}
----
// NOTCONSOLE

<1> The email must end with `example.com`
<2> The user must be enabled
<3> The result will be filtered to only contain users with at least one role that contains the substring `other`
<4> The offset to begin the search result is the 2nd (zero-based index) user
<5> The page size of the response is 2 users
<6> The result is sorted by `username` in descending order

The response contains a list of matched users along with their sort values:

[source,js]
----
{
    "total": 5,
    "count": 2,
    "users": [
        {
            "username": "ray",
            "roles": [
                "other_role3"
            ],
            "full_name": "Ray Nicholson",
            "email": "rayn@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "ray" <1>
            ]
        },
        {
            "username": "lorraine",
            "roles": [
                "other_role3"
            ],
            "full_name": "Lorraine Nicholson",
            "email": "lorraine@example.com",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "lorraine"
            ]
        }
    ]
}
----
// NOTCONSOLE

<1> The sort value is `username`