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, `2w` corresponds to 2 weeks. The forecast starts at the
  last record that was processed. For more information about time units, see
  <<time-units>>.

////
//Not a supported feature:
`end`::
  (string) The time that the forecast should end. The string can contain
  formatted dates, a number representing milliseconds since the epoch, or a
  number representing seconds since the epoch. It can also contain
  <<date-math,date math expressions>>. The default value is one day after
  the last record that was processed.

NOTE: You can specify either the `duration` or `end` parameter; if you specify
both, an error occurs.

////

==== 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>>.