Find users with a query
Generally available; Added in 8.14.0
All methods and paths for this operation:
GET
/_security/_query/user
POST
/_security/_query/user
Get information for users in a paginated manner. You can optionally filter the results with a query.
NOTE: As opposed to the get user API, built-in users are excluded from the result. This API is only for native users.
Required authorization
- Cluster privileges:
read_security
Body
-
The starting document offset. It must not be negative. By default, you cannot page through more than 10,000 hits using the
fromandsizeparameters. To page through more hits, use thesearch_afterparameter.Default value is
0. -
The number of hits to return. It must not be negative. By default, you cannot page through more than 10,000 hits using the
fromandsizeparameters. To page through more hits, use thesearch_afterparameter.Default value is
10. -
A field value.
A field value.
POST
/_security/_query/user
Console
POST /_security/_query/user?with_profile_uid=true
{
"query": {
"prefix": {
"roles": "other"
}
}
}resp = client.security.query_user(
with_profile_uid=True,
query={
"prefix": {
"roles": "other"
}
},
)const response = await client.security.queryUser({
with_profile_uid: "true",
query: {
prefix: {
roles: "other",
},
},
});response = client.security.query_user(
with_profile_uid: "true",
body: {
"query": {
"prefix": {
"roles": "other"
}
}
}
)$resp = $client->security()->queryUser([
"with_profile_uid" => "true",
"body" => [
"query" => [
"prefix" => [
"roles" => "other",
],
],
],
]);curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"query":{"prefix":{"roles":"other"}}}' "$ELASTICSEARCH_URL/_security/_query/user?with_profile_uid=true"client.security().queryUser(q -> q
.query(qu -> qu
.prefix(p -> p
.field("roles")
.value("other")
)
)
.withProfileUid(true)
);
Request examples
Query users by role prefix
Run `POST /_security/_query/user?with_profile_uid=true` to get users that have roles that are prefixed with `other`. It will also include the user `profile_uid` in the response.
{
"query": {
"prefix": {
"roles": "other"
}
}
}
Run `POST /_security/_query/user`. Use a `bool` query to issue complex logical conditions: The `email` must end with `example.com`. The user must be enabled. The result will be filtered to only contain users with at least one role that contains the substring `other`. The offset to begin the search result is the second (zero-based index) user. The page size of the response is two users. The result is sorted by `username` in descending order.
{
"query": {
"bool": {
"must": [
{
"wildcard": {
"email": "*example.com"
}
},
{
"term": {
"enabled": true
}
}
],
"filter": [
{
"wildcard": {
"roles": "*other*"
}
}
]
}
},
"from": 1,
"size": 2,
"sort": [
{ "username": { "order": "desc"} }
]
}
Response examples (200)
Query users by role prefix
A successful response from `POST /_security/_query/user?with_profile_uid=true` that contains users that have roles that are prefixed with `other`. It also includes the user `profile_uid` in the response.
{
"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"
}
]
}
A successful response from `POST /_security/_query/user` that uses a `bool` query to issue complex logical conditions and uses `from`, `size`, and `sort` to help paginate the result. The sort value is `username`.
{
"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"
]
},
{
"username": "lorraine",
"roles": [
"other_role3"
],
"full_name": "Lorraine Nicholson",
"email": "lorraine@example.com",
"metadata": {
"intelligence": 7
},
"enabled": true,
"_sort": [
"lorraine"
]
}
]
}
A successful response from `GET /_security/_query/user`, which lists all users. It returns a JSON structure that contains the information retrieved from one or more users.
{
"total": 2,
"count": 2,
"users": [
{
"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
}
]
}