IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Get datafeed statistics API Get anomaly detection jobs API »

› › ›

Get influencers API

edit

Get influencers API

edit

Retrieves anomaly detection job results for one or more influencers.

Request

edit

GET _ml/anomaly_detectors/<job_id>/results/influencers

Prerequisites

edit

If the Elasticsearch security features are enabled, you must have monitor_ml, monitor, manage_ml, or manage cluster privileges to use this API. You also need read index privilege on the index that stores the results. The machine_learning_admin and machine_learning_user roles provide these privileges. See Security privileges, Built-in roles, and Machine learning security privileges.

Description

edit

Influencers 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

edit

The 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

edit

GET _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
    },
  ...
  ]
}

« Get datafeed statistics API Get anomaly detection jobs API »