OpenSearch/docs/en/rest-api/ml/forecast.asciidoc

[role="xpack"]
[[ml-forecast]]
=== Forecast Jobs

The forecast jobs API uses historical behavior to predict the future behavior of
a time series.

==== Request

`POST _xpack/ml/anomaly_detectors/<job_id>/_forecast`


==== Description

You can use the API to estimate a time series value at a specific future date.
For example, you might want to determine how many users you can expect to visit
your website next Sunday at 0900.

You can also use it to estimate the probability of a time series value occurring
at a future date. For example, you might want to determine how likely it is that
your disk utilization will reach 100% before the end of next week.

Each time you call the API, it generates a new forecast and returns a unique ID.
Existing forecasts for the same job are not overwritten. You can use the forecast
ID to distinguish between forecasts that you generated at different times.

[NOTE]
===============================

* If you use an `over_field_name` property in your job, you cannot create a
forecast. For more information about this property, see <<ml-job-resource>>.
* The job must be open when you create a forecast. Otherwise, an error occurs.
===============================

==== Path Parameters

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


==== Query Parameters

`duration`::
  (time units) A period of time that indicates how far into the future to
  forecast. For example, `30d` corresponds to 30 days. The forecast starts at the
  last record that was processed. For more information about time units, see
  <<time-units>>.

`expires_in`::
  (time units) The period of time that forecast results are retained.
  After a forecast expires, the results are deleted. The default value is 14 days.
  If set to a value of `0`, the forecast is never automatically deleted.
  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 {xpack-ref}/security-privileges.html[Security Privileges].


==== Examples

The following example requests a 10 day forecast for the `total-requests` job:

[source,js]
--------------------------------------------------
POST _xpack/ml/anomaly_detectors/total-requests/_forecast
{
  "duration": "10d"
}
--------------------------------------------------
// CONSOLE
// TEST[skip:todo]

When the forecast is created, you receive the following results:
[source,js]
----
{
  "acknowledged": true,
  "forecast_id": 1507824469268
}
----

You can subsequently see the forecast in the *Single Metric Viewer* in {kib}
and in the results that you retrieve by using {ml} APIs such as the
<<ml-get-bucket,get bucket API>> and <<ml-get-record,get records API>>.