› › ›

Suggest user profile API

The user profile feature is designed only for use by Kibana and Elastic’s Observability, Enterprise Search, and Elastic Security solutions. Individual users and external applications should not call this API directly. Elastic reserves the right to change or remove this feature in future releases without prior notice.

Get suggestions for user profiles that match specified search criteria.

Request

GET /_security/profile/_suggest

POST /_security/profile/_suggest

Prerequisites

To use this API, you must have at least the read_security cluster privilege (or a greater privilege such as manage_user_profile or manage_security).

Query parameters

data: (Optional, string) Comma-separated list of filters for the data field of the profile document. To return all content, use data=*. To return a subset of content, use data=<key> to retrieve the content nested under the specified <key>. Defaults to returning no content.

Request body

name: (Optional, string) Query string used to match name-related fields in user profile documents. Name-related fields are the user’s username, full_name and email.
size: (Optional, integer) Number of profiles to return. Defaults to 10.
data: (Optional, string) Comma-separated list of filters for the data field of the profile document. It works the same way as the data query parameter.

It is an error to specify data as both the query parameter and the request body field.

hint

(Optional, object) Extra search criteria to improve relevance of the suggestion result. A profile matching the specified hint is ranked higher in the response. But not-matching the hint does not exclude a profile from the response as long as it matches the name field query.

Properties of hint:

uids: (Optional, list of strings) A list of Profile UIDs to match against.
labels: (Optional, object) A single key-value pair to match against the labels section of a profile. The key must be a string and the value must be either a string or a list of strings. A profile is considered matching if it matches at least one of the strings.

Response body

total: (object) Metadata about the number of matching profiles.
took: (integer) Milliseconds it took Elasticsearch to execute the request.
profiles: (array of objects) List of profile documents, ordered by relevance, that match the search criteria.

Examples

The following request get suggestions for profile documents with name-related fields matching jack. It specifies both uids and labels hints for better relevance:

resp = client.security.suggest_user_profiles(
    name="jack",
    hint={
        "uids": [
            "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
            "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
        ],
        "labels": {
            "direction": [
                "north",
                "east"
            ]
        }
    },
)
print(resp)

const response = await client.security.suggestUserProfiles({
  name: "jack",
  hint: {
    uids: [
      "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
    ],
    labels: {
      direction: ["north", "east"],
    },
  },
});
console.log(response);

POST /_security/profile/_suggest
{
  "name": "jack",  
  "hint": {
    "uids": [  
      "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0"
    ],
    "labels": {
      "direction": ["north", "east"]  
    }
  }
}

	A profile’s name-related fields must match `jack` for it to be included in the response.
	The `uids` hint include profile UIDs for both user `jackspa` and `jacknich`.
	The `labels` hint ranks profiles higher if their `direction` label matches either `north` or `east`.

The API returns:

{
  "took": 30,
  "total": {
    "value": 3,
    "relation": "eq"
  },
  "profiles": [
    {
      "uid": "u_79HkWkwmnBH5gqFKwoxggWPjEBOur1zLPXQPEl1VBW0_0",
      "user": {
        "username": "jacknich",    
        "roles": [ "admin", "other_role1" ],
        "realm_name": "native",
        "email" : "jacknich@example.com",
        "full_name": "Jack Nicholson"
      },
      "labels": {
        "direction": "north"
      },
      "data": {}
    },
    {
      "uid": "u_8RKO7AKfEbSiIHZkZZ2LJy2MUSDPWDr3tMI_CkIGApU_0",
      "user": {
        "username": "jackspa",    
        "roles": [ "user" ],
        "realm_name": "native",
        "email" : "jackspa@example.com",
        "full_name": "Jack Sparrow"
      },
      "labels": {
        "direction": "south"
      },
      "data": {}
    },
    {
      "uid": "u_P_0BMHgaOK3p7k-PFWUCbw9dQ-UFjt01oWJ_Dp2PmPc_0",
      "user": {
        "username": "jackrea",    
        "roles": [ "admin" ],
        "realm_name": "native",
        "email" : "jackrea@example.com",
        "full_name": "Jack Reacher"
      },
      "labels": {
        "direction": "west"
      },
      "data": {}
    }
  ]
}

	User `jacknich` is ranked highest because the profile matches both the `uids` and `labels` hints
	User `jackspa` is ranked second because the profile matches only the `uids` hint
	User `jackrea` is ranked lowest because the profile does not match any hints. However, it is not excluded from the response because it matches the `name` query.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/security-api-suggest-user-profile.html