--
:api: start-datafeed
:request: StartDatafeedRequest
:response: StartDatafeedResponse
--
[role="xpack"]
[id="{upid}-{api}"]
=== Start {dfeed} API

Starts a {ml} {dfeed} in the cluster. It accepts a +{request}+ object and
responds with a +{response}+ object.

[id="{upid}-{api}-request"]
==== Start {dfeed} request

A +{request}+ object is created referencing a non-null `datafeedId`.
All other fields are optional for the request.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request]
--------------------------------------------------
<1> Constructing a new request referencing an existing `datafeedId`.

==== Optional arguments

The following arguments are optional.

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-request-options]
--------------------------------------------------
<1> Set when the {dfeed} should end, the value is exclusive.
May be an epoch seconds, epoch millis or an ISO 8601 string.
"now" is a special value that indicates the current time.
If you do not specify an end time, the {dfeed} runs continuously.
<2> Set when the {dfeed} should start, the value is inclusive.
May be an epoch seconds, epoch millis or an ISO 8601 string.
If you do not specify a start time and the {dfeed} is associated with a new job,
the analysis starts from the earliest time for which data is available.
<3> Set the timeout for the request

[id="{upid}-{api}-response"]
==== Start {dfeed} response

["source","java",subs="attributes,callouts,macros"]
--------------------------------------------------
include-tagged::{doc-tests-file}[{api}-response]
--------------------------------------------------
<1> `isStarted()` from the +{response}+ is always `true` if the {dfeed} was
started successfully. (An exception would be thrown instead if the {dfeed}
was not started successfully.)
<2> `getNode()` returns the node that the {dfeed} was assigned to. If the
{dfeed} is allowed to open lazily and has not yet been assigned to a node
then an empty string is returned. If `getNode()` returns `null` then
the server is an old version that does not return node information.

include::../execution.asciidoc[]