elasticsearch/docs/reference/ml/anomaly-detection/apis/open-job.asciidoc

[role="xpack"]
[[ml-open-job]]
= Open {anomaly-jobs} API
++++
<titleabbrev>Open jobs</titleabbrev>
++++

Opens one or more {anomaly-jobs}.

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

`POST _ml/anomaly_detectors/{job_id}/_open`

[[ml-open-job-prereqs]]
== {api-prereq-title}

Requires the `manage_ml` cluster privilege. This privilege is included in the 
`machine_learning_admin` built-in role.

[[ml-open-job-desc]]
== {api-description-title}

An {anomaly-job} must be opened in order for it to be ready to receive and
analyze data. It can be opened and closed multiple times throughout its
lifecycle.

When you open a new job, it starts with an empty model.

When you open an existing job, the most recent model state is automatically
loaded. The job is ready to resume its analysis from where it left off, once new
data is received.

[[ml-open-job-path-parms]]
== {api-path-parms-title}

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

[[ml-open-job-query-parms]]
== {api-query-parms-title}

`timeout`::
(Optional, time) Controls the time to wait until a job has opened. The default
value is 30 minutes.

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

You can also specify the `timeout` query parameter in the request body.

[[ml-open-job-response-body]]
== {api-response-body-title}

`node`::
  (string) The ID of the node that the job was opened on. If the job is allowed to 
open lazily and has not yet been assigned to a node, this value is an empty string.

`opened`::
  (Boolean) For a successful response, this value is always `true`. On failure, an
  exception is returned instead.

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

[source,console]
--------------------------------------------------
POST _ml/anomaly_detectors/low_request_rate/_open
{
  "timeout": "35m"
}
--------------------------------------------------
// TEST[skip:Kibana sample data]

When the job opens, you receive the following results:

[source,console-result]
----
{
  "opened" : true,
  "node" : "node-1"
}
----