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

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

Deletes forecasts from a {ml} job.  

==== Request

`DELETE _xpack/ml/anomaly_detectors/<job_id>/_forecast` +

`DELETE _xpack/ml/anomaly_detectors/<job_id>/_forecast/<forecast_id>` +

`DELETE _xpack/ml/anomaly_detectors/<job_id>/_forecast/_all` 


==== Description

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 {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the Future].


==== Path Parameters

`job_id` (required)::
  (string) Identifier for the job.

`forecast_id`::
  (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. 

==== Request Parameters

`allow_no_forecasts`::
  (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`::
  (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`. For more information about time units, 
  see <<time-units>>.
  

==== Authorization

You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see {stack-ov}/security-privileges.html[Security Privileges].

==== Examples

The following example deletes all forecasts from the `total-requests` job:

[source,js]
--------------------------------------------------
DELETE _xpack/ml/anomaly_detectors/total-requests/_forecast/_all
--------------------------------------------------
// CONSOLE
// TEST[skip:setup:server_metrics_openjob]

If the request does not encounter errors, you receive the following result:
[source,js]
----
{
  "acknowledged": true
}
----
// NOTCONSOLE