Find users with a query Generally available; Added in 8.14.0

POST /_security/_query/user
Api key auth Basic auth Bearer auth

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

Query parameters

  • with_profile_uid boolean

    Determines whether to retrieve the user profile UID, if it exists, for the users.

application/json

Body

  • query object

    A query to filter which users to return. If the query parameter is missing, it is equivalent to a match_all query. The query supports a subset of query types, including match_all, bool, term, terms, match, ids, prefix, wildcard, exists, range, and simple_query_string. You can query the following information associated with user: username, roles, enabled, full_name, and email.

    Hide query attributes Show query attributes object
    • match object

      Returns users that match a provided text, number, date or boolean value. The provided text is analyzed before matching.

    • prefix object

      Returns users that contain a specific prefix in a provided field.

    • range object

      Returns users that contain terms within a provided range.

    • term object

      Returns users that contain an exact term in a provided field. To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.

    • wildcard object

      Returns users that contain terms matching a wildcard pattern.

  • from number

    The starting document offset. It must not be negative. 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 parameter.

    Default value is 0.

  • sort string | object | array[string | object]

    The sort definition. Fields eligible for sorting are: username, roles, enabled. In addition, sort can also be applied to the _doc field to sort by index order.

    One of:
    Field string SortOptions object array-2 array[string | object]

    The sort definition. Fields eligible for sorting are: username, roles, enabled. In addition, sort can also be applied to the _doc field to sort by index order.

    The sort definition. Fields eligible for sorting are: username, roles, enabled. In addition, sort can also be applied to the _doc field to sort by index order.

  • 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 from and size parameters. To page through more hits, use the search_after parameter.

    Default value is 10.

  • search_after array[number | string | boolean | null]

    The search after definition

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • total number Required

      The total number of users found.

    • count number Required

      The number of users returned in the response.

    • users array[object] Required

      A list of users that match the query.

      Hide users attributes Show users attributes object
POST /_security/_query/user 
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
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)
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
        }
    ]
}