Get influencers API
editGet influencers API
editRetrieves anomaly detection job results for one or more influencers.
Request
editGET _ml/anomaly_detectors/<job_id>/results/influencers
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have
monitor_ml
,monitor
,manage_ml
, ormanage
cluster privileges to use this API. You also needread
index privilege on the index that stores the results. Themachine_learning_admin
andmachine_learning_user
roles provide these privileges. See Security privileges, Built-in roles, and Machine learning security privileges.
Description
editInfluencers are the entities that have contributed to, or are to blame for,
the anomalies. Influencer results are available only if an
influencer_field_name
is specified in the job configuration.
Path parameters
edit-
<job_id>
- (Required, string) Identifier for the anomaly detection job.
Request body
edit-
desc
- (Optional, Boolean) If true, the results are sorted in descending order.
-
end
- (Optional, string) Returns influencers with timestamps earlier than this time.
-
exclude_interim
-
(Optional, Boolean)
If
true
, the output excludes interim results. By default, interim results are included. -
influencer_score
- (Optional, double) Returns influencers with anomaly scores greater than or equal to this value.
-
page
.from
- (Optional, integer) Skips the specified number of influencers.
-
page
.size
- (Optional, integer) Specifies the maximum number of influencers to obtain.
-
sort
-
(Optional, string) Specifies the sort field for the requested influencers. By
default, the influencers are sorted by the
influencer_score
value. -
start
- (Optional, string) Returns influencers with timestamps after this time.
Response body
editThe API returns an array of influencer objects, which have the following properties:
-
bucket_span
-
(number)
The length of the bucket in seconds. This value matches the
bucket_span
that is specified in the job. -
influencer_score
-
(number) A normalized score between 0-100, which is based on the probability of
the influencer in this bucket aggregated across detectors. Unlike
initial_influencer_score
, this value will be updated by a re-normalization process as new data is analyzed. -
influencer_field_name
- (string) The field name of the influencer.
-
influencer_field_value
- (string) The entity that influenced, contributed to, or was to blame for the anomaly.
-
initial_influencer_score
- (number) A normalized score between 0-100, which is based on the probability of the influencer aggregated across detectors. This is the initial value that was calculated at the time the bucket was processed.
-
is_interim
-
(Boolean)
If
true
, this is an interim result. In other words, the results are calculated based on partial input data. -
job_id
- (string) Identifier for the anomaly detection job.
-
probability
-
(number) The probability that the influencer has this behavior, in the range 0
to 1. This value can be held to a high precision of over 300 decimal places, so
the
influencer_score
is provided as a human-readable and friendly interpretation of this. -
result_type
-
(string) Internal. This value is always set to
influencer
. -
timestamp
- (date) The start time of the bucket for which these results were calculated.
Additional influencer properties are added, depending on the fields being
analyzed. For example, if it’s analyzing user_name
as an influencer, then a
field user_name
is added to the result document. This information enables you to
filter the anomaly results more easily.
Examples
editGET _ml/anomaly_detectors/high_sum_total_sales/results/influencers { "sort": "influencer_score", "desc": true }
In this example, the API returns the following information, sorted based on the influencer score in descending order:
{ "count": 189, "influencers": [ { "job_id": "high_sum_total_sales", "result_type": "influencer", "influencer_field_name": "customer_full_name.keyword", "influencer_field_value": "Wagdi Shaw", "customer_full_name.keyword" : "Wagdi Shaw", "influencer_score": 99.02493, "initial_influencer_score" : 94.67233079580171, "probability" : 1.4784807245686567E-10, "bucket_span" : 3600, "is_interim" : false, "timestamp" : 1574661600000 }, ... ] }