elasticsearch/docs/reference/ml/apis/preview-datafeed.asciidoc

[role="xpack"]
[testenv="platinum"]
[[ml-preview-datafeed]]
=== Preview {dfeeds} API

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

Previews a {dfeed}.

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

`GET _ml/datafeeds/<datafeed_id>/_preview`

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

The preview {dfeeds} API returns the first "page" of results from the `search`
that is created by using the current {dfeed} settings. This preview shows the
structure of the data that will be passed to the anomaly detection engine.

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

`datafeed_id` (required)::
  (string) Identifier for the {dfeed}

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

If {es} {security-features} are enabled, you must have `monitor_ml`, `monitor`,
`manage_ml`, or `manage` cluster privileges to use this API. For more
information, see
{stack-ov}/security-privileges.html[Security privileges].

[[ml-preview-datafeed-security]]
==== Security Integration

When {es} {security-features} are enabled, the {dfeed} query is previewed using
the credentials of the user calling the preview {dfeed} API.  When the {dfeed}
is started it runs the query using the roles of the last user to
create or update it.  If the two sets of roles differ then the preview may
not accurately reflect what the {dfeed} will return when started.  To avoid
such problems, the same user that creates/updates the {dfeed} should preview
it to ensure it is returning the expected data.

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

The following example obtains a preview of the `datafeed-farequote` {dfeed}:

[source,js]
--------------------------------------------------
GET _ml/datafeeds/datafeed-farequote/_preview
--------------------------------------------------
// CONSOLE
// TEST[skip:setup:farequote_datafeed]

The data that is returned for this example is as follows:
[source,js]
----
[
  {
    "time": 1454803200000,
    "airline": "JZA",
    "doc_count": 5,
    "responsetime": 990.4628295898438
  },
  {
    "time": 1454803200000,
    "airline": "JBU",
    "doc_count": 23,
    "responsetime": 877.5927124023438
  },
  {
    "time": 1454803200000,
    "airline": "KLM",
    "doc_count": 42,
    "responsetime": 1355.481201171875
  }
]
----
// TESTRESPONSE