[role="xpack"]
[testenv="platinum"]
[[ml-put-job]]
=== Create {anomaly-jobs} API
++++
<titleabbrev>Create jobs</titleabbrev>
++++

Instantiates an {anomaly-job}.

[[ml-put-job-request]]
==== {api-request-title}

`PUT _ml/anomaly_detectors/<job_id>`

[[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
<<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}

`<job_id>`::
(Required, string)
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-define]

[[ml-put-job-request-body]]
==== {api-request-body-title}

`allow_lazy_open`::
(Optional, boolean)
include::{docdir}/ml/ml-shared.asciidoc[tag=allow-lazy-open]

[[put-analysisconfig]]`analysis_config`::
(Required, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-config]

[[put-analysislimits]]`analysis_limits`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-limits]

`background_persist_interval`::
(Optional, <<time-units, time units>>)
include::{docdir}/ml/ml-shared.asciidoc[tag=background-persist-interval]

[[put-customsettings]]`custom_settings`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-settings]

[[put-datadescription]]`data_description`::
(Required, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=data-description]

`description`::
  (Optional, string) A description of the job.

`groups`::
(Optional, array of strings)
include::{docdir}/ml/ml-shared.asciidoc[tag=groups]

`model_plot_config`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config]

`model_snapshot_retention_days`::
(Optional, long)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-snapshot-retention-days]

`renormalization_window_days`::
(Optional, long)
include::{docdir}/ml/ml-shared.asciidoc[tag=renormalization-window-days]

`results_index_name`::
(Optional, string)
include::{docdir}/ml/ml-shared.asciidoc[tag=results-index-name]

`results_retention_days`::
(Optional, long)
include::{docdir}/ml/ml-shared.asciidoc[tag=results-retention-days]

[[ml-put-job-example]]
==== {api-examples-title}

The following example creates the `total-requests` job:

[source,console]
--------------------------------------------------
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"
  }
}
--------------------------------------------------

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

[source,console-result]
----
{
  "job_id" : "total-requests",
  "job_type" : "anomaly_detector",
  "job_version" : "8.0.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",
  "allow_lazy_open" : false
}
----
// TESTRESPONSE[s/"job_version" : "8.0.0"/"job_version" : $body.job_version/]
// TESTRESPONSE[s/1562352500629/$body.$_path/]