Find users with a query

POST also GET /_security/_query/user

Api key auth Basic auth Bearer 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.

Query Parameters

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

Response

application/json

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.

Request Console 1 / 8 languages

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

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

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.

Request Console 1 / 2 languages

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

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

Response

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

Required authorization

Query Parameters

Request { query , from , sort , size , search_after , }

Response

Request