OpenSearch/docs/reference/ml/apis/flush-job.asciidoc

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

Forces any buffered data to be processed by the job.

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

`POST _ml/anomaly_detectors/<job_id>/_flush`

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

* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
{stack-ov}/security-privileges.html[Security privileges].

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

The flush jobs API is only applicable when sending data for analysis using the
<<ml-post-data,post data API>>. Depending on the content of the buffer, then it
might additionally calculate new results.

Both flush and close operations are similar, however the flush is more efficient
if you are expecting to send more data for analysis. When flushing, the job
remains open and is available to continue analyzing data. A close operation
additionally prunes and persists the model state to disk and the job must be
opened again before analyzing further data.

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

`<job_id>` (Required)::
(string) Identifier for the job.

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

`advance_time` (Optional)::
  (string) Specifies to advance to a particular time value. Results are
  generated and the model is updated for data from the specified time interval.

`calc_interim` (Optional)::
  (boolean) If true, calculates the interim results for the most recent bucket
  or all buckets within the latency period.

`end` (Optional)::
  (string) When used in conjunction with `calc_interim`, specifies the range
  of buckets on which to calculate interim results.

`skip_time` (Optional)::
  (string) Specifies to skip to a particular time value. Results are not
  generated and the model is not updated for data from the specified time
  interval.

`start` (Optional)::
  (string) When used in conjunction with `calc_interim`, specifies the range of
  buckets on which to calculate interim results.

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

The following example flushes the `total-requests` job:

[source,js]
--------------------------------------------------
POST _ml/anomaly_detectors/total-requests/_flush
{
  "calc_interim": true
}
--------------------------------------------------
// CONSOLE
// TEST[skip:setup:server_metrics_openjob]

When the operation succeeds, you receive the following results:
[source,js]
----
{
  "flushed": true,
  "last_finalized_bucket_end": 1455234900000
}
----
//TESTRESPONSE[s/"last_finalized_bucket_end": 1455234900000/"last_finalized_bucket_end": $body.last_finalized_bucket_end/]

The `last_finalized_bucket_end` provides the timestamp (in
milliseconds-since-the-epoch) of the end of the last bucket that was processed.

If you want to flush the job to a specific timestamp, you can use the
`advance_time` or `skip_time` parameters.  For example, to advance to 11 AM GMT
on January 1, 2018:

[source,js]
--------------------------------------------------
POST _ml/anomaly_detectors/total-requests/_flush
{
  "advance_time": "1514804400"
}
--------------------------------------------------
// CONSOLE
// TEST[skip:setup:server_metrics_openjob]

When the operation succeeds, you receive the following results:
[source,js]
----
{
  "flushed": true,
  "last_finalized_bucket_end": 1514804400000
}
----
// TESTRESPONSE