[role="xpack"] [testenv="platinum"] [[ml-put-job]] === Create {anomaly-jobs} API [subs="attributes"] ++++ Create {anomaly-jobs} ++++ Instantiates an {anomaly-job}. [[ml-put-job-request]] ==== {api-request-title} `PUT _ml/anomaly_detectors/` [[ml-put-job-prereqs]] ==== {api-prereq-title} * If the {es} {security-features} are enabled, you must have `manage_ml` or `manage` cluster privileges to use this API. See {stack-ov}/security-privileges.html[Security privileges]. [[ml-put-job-desc]] ==== {api-description-title} IMPORTANT: You must use {kib} or this API to create an {anomaly-job}. Do not put a job directly to the `.ml-config` index using the {es} index API. If {es} {security-features} are enabled, do not give users `write` privileges on the `.ml-config` index. [[ml-put-job-path-parms]] ==== {api-path-parms-title} ``:: (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. [[ml-put-job-request-body]] ==== {api-request-body-title} `analysis_config`:: (Required, object) The analysis configuration, which specifies how to analyze the data. See <>. `analysis_limits`:: (Optional, object) Specifies runtime limits for the job. See <>. `background_persist_interval`:: (Optional, time units) Advanced configuration option. The time between each periodic persistence of the model. See <>. `custom_settings`:: (Optional, object) Advanced configuration option. Contains custom meta data about the job. See <>. `data_description`:: (Required, object) Describes the format of the input data. This object is required, but it can be empty (`{}`). See <>. `description`:: (Optional, string) A description of the job. `groups`:: (Optional, array of strings) A list of job groups. See <>. `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_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 <>. `results_index_name`:: (Optional, string) A text string that affects the name of the {ml} 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 <>. [[ml-put-job-example]] ==== {api-examples-title} The following example creates the `total-requests` job: [source,js] -------------------------------------------------- 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" } } -------------------------------------------------- // CONSOLE When the job is created, you receive the following results: [source,js] ---- { "job_id" : "total-requests", "job_type" : "anomaly_detector", "job_version" : "7.4.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" } ---- // TESTRESPONSE[s/"job_version" : "7.4.0"/"job_version" : $body.job_version/] // TESTRESPONSE[s/1562352500629/$body.$_path/]