elasticsearch/docs/reference/ml/anomaly-detection/apis/delete-forecast.asciidoc

[role="xpack"]
[testenv="platinum"]
[[ml-delete-forecast]]
= Delete forecast API
++++
<titleabbrev>Delete forecast</titleabbrev>
++++

Deletes forecasts from a {ml} job.  

[[ml-delete-forecast-request]]
== {api-request-title}

`DELETE _ml/anomaly_detectors/<job_id>/_forecast` +

`DELETE _ml/anomaly_detectors/<job_id>/_forecast/<forecast_id>` +

`DELETE _ml/anomaly_detectors/<job_id>/_forecast/_all`

[[ml-delete-forecast-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
<<security-privileges>> and {ml-docs-setup-privileges}.

[[ml-delete-forecast-desc]]
== {api-description-title}

By default, forecasts are retained for 14 days. You can specify a different 
retention period with the `expires_in` parameter in the
<<ml-forecast,forecast jobs API>>. The delete forecast API enables you to delete
one or more forecasts before they expire.

NOTE: When you delete a job, its associated forecasts are deleted. 

For more information, see
{ml-docs}/ml-overview.html#ml-forecasting[Forecasting the future].

[[ml-delete-forecast-path-parms]]
== {api-path-parms-title}

`<forecast_id>`::
(Optional, string) A comma-separated list of forecast identifiers. If you do not
specify this optional parameter or if you specify `_all`, the API deletes all
forecasts from the job. 
  
`<job_id>`::
(Required, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
  

[[ml-delete-forecast-query-parms]]
== {api-query-parms-title}

`allow_no_forecasts`::
  (Optional, boolean) Specifies whether an error occurs when there are no
  forecasts. In particular, if this parameter is set to `false` and there are no 
  forecasts associated with the job, attempts to delete all forecasts return an
  error. The default value is `true`.

`timeout`::
  (Optional, <<time-units, time units>>) Specifies the period of time to wait 
  for the completion of the delete operation. When this period of time elapses, 
  the API fails and returns an error. The default value is `30s`.

[[ml-delete-forecast-example]]
== {api-examples-title}

[source,console]
--------------------------------------------------
DELETE _ml/anomaly_detectors/total-requests/_forecast/_all
--------------------------------------------------
// TEST[skip:setup:server_metrics_openjob]

If the request does not encounter errors, you receive the following result:

[source,js]
----
{
  "acknowledged": true
}
----
// NOTCONSOLE