[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/]