Query parameters

  • with_profile_uidboolean

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

application/json

Body

  • queryobject
    Hide query attributes Show query attributes object
    • ids
    • bool
    • exists
    • matchobject

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

    • match_all
    • prefixobject

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

    • rangeobject

      Returns users that contain terms within a provided range.

    • simple_query_string
    • termobject

      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.

    • terms
    • wildcardobject

      Returns users that contain terms matching a wildcard pattern.

  • fromnumber

    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.

  • sortstring | object | array[string | object]

    One of:
    FieldstringSortOptionsobjectSortarray[string | object]

    Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

    One of:
    FieldstringSortOptionsobject

    Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • sizenumber

    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_afterarray[number | string | boolean | null | object]

    A field value.

    A field value.

    One of:
    FieldValuenumberFieldValuenumberFieldValuestringFieldValuebooleanFieldValuestring | nullFieldValueobject

Responses

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
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": "[email protected]",
            "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": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true,
            "_sort": [
                "ray" 
            ]
        },
        {
            "username": "lorraine",
            "roles": [
                "other_role3"
            ],
            "full_name": "Lorraine Nicholson",
            "email": "[email protected]",
            "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": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        },
        {
            "username": "sandrakn",
            "roles": [
                "admin",
                "other_role1"
            ],
            "full_name": "Sandra Knight",
            "email": "[email protected]",
            "metadata": {
                "intelligence": 7
            },
            "enabled": true
        }
    ]
}