New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Close anomaly detection jobs API Create calendar API »
Elastic Docs ›Elasticsearch Guide [7.3] ›REST APIs ›Machine learning anomaly detection APIs

Create anomaly detection jobs API

edit

Create anomaly detection jobs API

edit

Instantiates an anomaly detection job.

Request

edit

PUT _ml/anomaly_detectors/<job_id>

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have manage_ml or manage cluster privileges to use this API. See Security privileges.

Description

edit

You must use Kibana or this API to create an anomaly detection job. Do not put a job directly to the .ml-config index using the Elasticsearch index API. If Elasticsearch security features are enabled, do not give users write privileges on the .ml-config index.

Path parameters

edit
<job_id>
(Required, string) Identifier for the job. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.

Request body

edit
analysis_config
(Required, object) The analysis configuration, which specifies how to analyze the data. See analysis configuration objects.
analysis_limits
(Optional, object) Specifies runtime limits for the job. See analysis limits.
background_persist_interval
(Optional, time units) Advanced configuration option. The time between each periodic persistence of the model. See Job resources.
custom_settings
(Optional, object) Advanced configuration option. Contains custom meta data about the job. See Job resources.
data_description
(Required, object) Describes the format of the input data. This object is required, but it can be empty ({}). See data description objects.
description
(Optional, string) A description of the job.
groups
(Optional, array of strings) A list of job groups. See Job resources.
model_plot_config
(Optional, object) Advanced configuration option. Specifies to store model information along with the results. This adds overhead to the performance of the system and is not feasible for jobs with many entities, see Model Plot Config.
model_snapshot_retention_days
(Optional, long) The time in days that model snapshots are retained for the job. Older snapshots are deleted. The default value is 1, which means snapshots are retained for one day (twenty-four hours).
renormalization_window_days
(Optional, long) Advanced configuration option. The period over which adjustments to the score are applied, as new data is seen. See Job resources.
results_index_name
(Optional, string) A text string that affects the name of the machine learning results index. The default value is shared, which generates an index named .ml-anomalies-shared.
results_retention_days
(Optional, long) Advanced configuration option. The number of days for which job results are retained. See Job resources.

Examples

edit

The following example creates the total-requests job:

PUT _ml/anomaly_detectors/total-requests
{
  "description" : "Total sum of requests",
  "analysis_config" : {
    "bucket_span":"10m",
    "detectors": [
      {
        "detector_description": "Sum of total",
        "function": "sum",
        "field_name": "total"
      }
    ]
  },
  "data_description" : {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
Copy as curlTry in Elastic 

When the job is created, you receive the following results:

{
  "job_id" : "total-requests",
  "job_type" : "anomaly_detector",
  "job_version" : "7.3.0",
  "description" : "Total sum of requests",
  "create_time" : 1562352500629,
  "analysis_config" : {
    "bucket_span" : "10m",
    "detectors" : [
      {
        "detector_description" : "Sum of total",
        "function" : "sum",
        "field_name" : "total",
        "detector_index" : 0
      }
    ],
    "influencers" : [ ]
  },
  "analysis_limits" : {
    "model_memory_limit" : "1024mb",
    "categorization_examples_limit" : 4
  },
  "data_description" : {
    "time_field" : "timestamp",
    "time_format" : "epoch_ms"
  },
  "model_snapshot_retention_days" : 1,
  "results_index_name" : "shared"
}
« Close anomaly detection jobs API Create calendar API »

On this page

Was this helpful?
Feedback