Find users with a query
Added in 8.14.0
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.
Query parameters
-
with_profile_uid
boolean Determines whether to retrieve the user profile UID, if it exists, for the users.
Body
-
query
object -
from
number 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. -
size
number 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. -
search_after
array[number | string | boolean | null] A field value.
POST
/_security/_query/user
curl \
--request POST 'http://api.example.com/_security/_query/user' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '"{\n \"query\": {\n \"prefix\": {\n \"roles\": \"other\"\n }\n }\n}"'
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
}
]
}