elasticsearch/docs/reference/ml/apis/put-job.asciidoc

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

Instantiates a job.

==== Request

`PUT _ml/anomaly_detectors/<job_id>`

===== Description

IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
            directly to the `.ml-config` index using the Elasticsearch index API.
            If {es} {security-features} are enabled, do not give users `write`
            privileges on the `.ml-config` index.


==== Path Parameters

`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

`analysis_config`::
  (object) The analysis configuration, which specifies how to analyze the data.
  See <<ml-analysisconfig, analysis configuration objects>>.

`analysis_limits`::
  (object) Specifies runtime limits for the job. See
  <<ml-apilimits,analysis limits>>.

`background_persist_interval`::
  (time units) Advanced configuration option. The time between each periodic
  persistence of the model. See <<ml-job-resource>>.

`custom_settings`::
  (object) Advanced configuration option. Contains custom meta data about the
  job. See <<ml-job-resource>>.

`data_description` (required)::
  (object) Describes the format of the input data. This object is required, but
  it can be empty (`{}`). See <<ml-datadescription,data description objects>>.

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

`groups`::
  (array of strings) A list of job groups. See <<ml-job-resource>>.

`model_plot_config`::
  (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 <<ml-apimodelplotconfig>>.

`model_snapshot_retention_days`::
  (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`::
  (long) Advanced configuration option. The period over which adjustments to the
  score are applied, as new data is seen. See <<ml-job-resource>>.

`results_index_name`::
  (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`::
  (long) Advanced configuration option. The number of days for which job results
  are retained. See <<ml-job-resource>>.

==== Authorization

You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].


==== Examples

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
// TEST[skip:need-licence]

When the job is created, you receive the following results:
[source,js]
----
{
  "job_id": "total-requests",
  "job_type": "anomaly_detector",
  "job_version": "7.0.0-alpha1",
  "description": "Total sum of requests",
  "create_time": 1517011406091,
  "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.0.0-alpha1"/"job_version": $body.job_version/]
// TESTRESPONSE[s/"create_time": 1517011406091/"create_time": $body.create_time/]