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.

highlight#highlightFromAnchor" href="#topic-required-authorization"> 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

Responses

POST /_security/_query/user
dropdown#toggle click@window->dropdown#hide touchend@window->dropdown#hide" data-dropdown-target="button" data-scrollable="false" data-headings="false" aria-expanded="false" aria-haspopup="true" role="menu" tabindex="0">
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
dropdown#toggle click@window->dropdown#hide touchend@window->dropdown#hide" data-dropdown-target="button" data-scrollable="false" data-headings="false" aria-expanded="false" aria-haspopup="true" role="menu" tabindex="0">
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)
dropdown#toggle click@window->dropdown#hide touchend@window->dropdown#hide" data-dropdown-target="button" data-scrollable="false" data-headings="false" aria-expanded="false" aria-haspopup="true" role="menu" tabindex="0">
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
        }
    ]
}