OpenSearch/docs/reference/ml/anomaly-detection/apis/start-datafeed.asciidoc

[role="xpack"]
[testenv="platinum"]
[[ml-start-datafeed]]
=== Start {dfeeds} API

[subs="attributes"]
++++
<titleabbrev>Start {dfeeds}</titleabbrev>
++++

Starts one or more {dfeeds}.

[[ml-start-datafeed-request]]
==== {api-request-title}

`POST _ml/datafeeds/<feed_id>/_start`

[[ml-start-datafeed-prereqs]]
==== {api-prereq-title}

* Before you can start a {dfeed}, the {anomaly-job} must be open. Otherwise, an
error occurs.
* If {es} {security-features} are enabled, you must have `manage_ml` or `manage`
cluster privileges to use this API. See
<<security-privileges>>.

[[ml-start-datafeed-desc]]
==== {api-description-title}

A {dfeed} must be started in order to retrieve data from {es}.
A {dfeed} can be started and stopped multiple times throughout its lifecycle.

When you start a {dfeed}, you can specify a start time.  This enables you to
include a training period, providing you have this data available in {es}.
If you want to analyze from the beginning of a dataset, you can specify any date
earlier than that beginning date.

If you do not specify a start time and the {dfeed} is associated with a new
{anomaly-job}, the analysis starts from the earliest time for which data is
available.

When you start a {dfeed}, you can also specify an end time. If you do so, the
job analyzes data from the start time until the end time, at which point the
analysis stops.  This scenario is useful for a one-off batch analysis.  If you
do not specify an end time, the {dfeed} runs continuously.

The `start` and `end` times can be specified by using one of the
following formats: +

- ISO 8601 format with milliseconds, for example `2017-01-22T06:00:00.000Z`
- ISO 8601 format without milliseconds, for example `2017-01-22T06:00:00+00:00`
- Milliseconds since the epoch, for example `1485061200000`

Date-time arguments using either of the ISO 8601 formats must have a time zone
designator, where Z is accepted as an abbreviation for UTC time.

NOTE: When a URL is expected (for example, in browsers), the `+` used in time
zone designators must be encoded as `%2B`.

If the system restarts, any jobs that had {dfeeds} running are also restarted.

When a stopped {dfeed} is restarted, it continues processing input data from
the next millisecond after it was stopped. If new data was indexed for that
exact millisecond between stopping and starting, it will be ignored.
If you specify a `start` value that is earlier than the timestamp of the latest
processed record, the {dfeed} continues from 1 millisecond after the timestamp
of the latest processed record.

IMPORTANT: When {es} {security-features} are enabled, your {dfeed} remembers
which roles the last user to create or update it had at the time of
creation/update and runs the query using those same roles. If you provided
<<http-clients-secondary-authorization,secondary authorization headers>> when
you created or updated the {dfeed}, those credentials are used instead.

[[ml-start-datafeed-path-parms]]
==== {api-path-parms-title}

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

[[ml-start-datafeed-request-body]]
==== {api-request-body-title}

`end`::
  (Optional, string) The time that the {dfeed} should end. This value is
  exclusive. The default value is an empty string.

`start`::
  (Optional, string) The time that the {dfeed} should begin. This value is
  inclusive. The default value is an empty string.

`timeout`::
  (Optional, time) Controls the amount of time to wait until a {dfeed} starts.
  The default value is 20 seconds.

[[ml-start-datafeed-response-body]]
==== {api-response-body-title}

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

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

[[ml-start-datafeed-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
POST _ml/datafeeds/datafeed-total-requests/_start
{
  "start": "2017-04-07T18:22:16Z"
}
--------------------------------------------------
// TEST[skip:setup:server_metrics_openjob]

When the {dfeed} starts, you receive the following results:

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