Find users with a query

POST also GET /_security/_query/user

Auth

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 privileges

Cluster privileges read_security

Query parameters

with_profile_uid boolean · default: false: Determines whether to retrieve the user profile UID, if it exists, for the users.

Request 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.
from number · default: 0: 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.
sort union oneOf: 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.; Reference
size number · default: 10: 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.
search_after union[]: The search after definition; Reference

Response

application/json

total number required: The total number of users found.
count number required: The number of users returned in the response.
users object[] required: A list of users that match the query.

Examples

Request Console 1 / 8 languages

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.

Console Kibana Dev Tools

POST /_security/_query/user?with_profile_uid=true
{
    "query": {
        "prefix": {
            "roles": "other"
        }
    }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.queryUser({
  with_profile_uid: "true",
  query: {
    prefix: {
      roles: "other",
    },
  },
});

Python Elasticsearch Python Client

resp = client.security.query_user(
    with_profile_uid=True,
    query={
        "prefix": {
            "roles": "other"
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/_query/user?with_profile_uid=true" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "prefix": {
        "roles": "other"
      }
    }
  }'

Java Elasticsearch Java Client

client.security().queryUser(q -> q
    .query(qu -> qu
        .prefix(p -> p
            .field("roles")
            .value("other")
        )
    )
    .withProfileUid(true)
);

C# Elasticsearch .NET Client

var response = await client.Security
    .QueryUserAsync(d1 => d1
        .WithProfileUid(true)
        .Query(d2 => d2
            .Prefix(d3 => d3
                .Field(x => x.Roles)
                .Value("other")
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->queryUser([
    "with_profile_uid" => "true",
    "body" => [
        "query" => [
            "prefix" => [
                "roles" => "other",
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.query_user(
  with_profile_uid: "true",
  body: {
    "query": {
      "prefix": {
        "roles": "other"
      }
    }
  }
)

Response

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"
        }
    ]
}

Request Console 1 / 8 languages

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.

Console Kibana Dev Tools

POST /_security/_query/user
{
  "query": {
    "bool": {
      "must": [
        {
          "wildcard": {
            "email": "*example.com" 
          }
        },
        {
          "term": {
            "enabled": true 
          }
        }
      ],
      "filter": [
        {
          "wildcard": {
            "roles": "*other*" 
          }
        }
      ]
    }
  },
  "from": 1, 
  "size": 2, 
  "sort": [
    { "username": { "order": "desc"} } 
  ]
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.queryUser({
  query: {
    bool: {
      must: [
        {
          wildcard: {
            email: "*example.com",
          },
        },
        {
          term: {
            enabled: true,
          },
        },
      ],
      filter: [
        {
          wildcard: {
            roles: "*other*",
          },
        },
      ],
    },
  },
  from: 1,
  size: 2,
  sort: [
    {
      username: {
        order: "desc",
      },
    },
  ],
});

Python Elasticsearch Python Client

resp = client.security.query_user(
    query={
        "bool": {
            "must": [
                {
                    "wildcard": {
                        "email": "*example.com"
                    }
                },
                {
                    "term": {
                        "enabled": True
                    }
                }
            ],
            "filter": [
                {
                    "wildcard": {
                        "roles": "*other*"
                    }
                }
            ]
        }
    },
    from_=1,
    size=2,
    sort=[
        {
            "username": {
                "order": "desc"
            }
        }
    ],
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/_query/user" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "must": [
          {
            "wildcard": {
              "email": "*example.com"
            }
          },
          {
            "term": {
              "enabled": true
            }
          }
        ],
        "filter": [
          {
            "wildcard": {
              "roles": "*other*"
            }
          }
        ]
      }
    },
    "from": 1,
    "size": 2,
    "sort": [
      {
        "username": {
          "order": "desc"
        }
      }
    ]
  }'

Java Elasticsearch Java Client

client.security().queryUser(q -> q
    .from(1)
    .query(qu -> qu
        .bool(b -> b
            .filter(f -> f
                .wildcard(w -> w
                    .field("roles")
                    .value("*other*")
                )
            )
            .must(List.of(Query.of(que -> que
                    .wildcard(w -> w
                        .field("email")
                        .value("*example.com")
                )),Query.of(quer -> quer
                    .term(t -> t
                        .field("enabled")
                        .value(FieldValue.of(true))
                ))))
        )
    )
    .size(2)
    .sort(s -> s
        .field(fi -> fi
            .field("username")
            .order(SortOrder.Desc)
        )
    )
);

C# Elasticsearch .NET Client

var response = await client.Security
    .QueryUserAsync(d1 => d1
        .From(1)
        .Query(d2 => d2
            .Bool(d3 => d3
                .Filter(d4 => d4
                    .Wildcard(d5 => d5
                        .Field(x => x.Roles)
                        .Value("*other*")
                    )
                )
                .Must(d4 => d4
                    .Wildcard(d5 => d5
                        .Field(x => x.Email)
                        .Value("*example.com")
                    ), d4 => d4
                    .Term(d5 => d5
                        .Field(x => x.Enabled)
                        .Value(true)
                    )
                )
            )
        )
        .Size(2)
        .Sort(d2 => d2
            .Field(d3 => d3
                .Field(x => x.Username)
                .Order(SortOrder.Desc)
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->queryUser([
    "body" => [
        "query" => [
            "bool" => [
                "must" => array(
                    [
                        "wildcard" => [
                            "email" => "*example.com",
                        ],
                    ],
                    [
                        "term" => [
                            "enabled" => true,
                        ],
                    ],
                ),
                "filter" => array(
                    [
                        "wildcard" => [
                            "roles" => "*other*",
                        ],
                    ],
                ),
            ],
        ],
        "from" => 1,
        "size" => 2,
        "sort" => array(
            [
                "username" => [
                    "order" => "desc",
                ],
            ],
        ),
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.query_user(
  body: {
    "query": {
      "bool": {
        "must": [
          {
            "wildcard": {
              "email": "*example.com"
            }
          },
          {
            "term": {
              "enabled": true
            }
          }
        ],
        "filter": [
          {
            "wildcard": {
              "roles": "*other*"
            }
          }
        ]
      }
    },
    "from": 1,
    "size": 2,
    "sort": [
      {
        "username": {
          "order": "desc"
        }
      }
    ]
  }
)

Response

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"
            ]
        }
    ]
}