Forecast Run API Reference

The Forecast Run API lets you trigger an automatic forecast run on an existing forecast and poll for the result. All run operations are asynchronous: the POST endpoint returns immediately with a jobId, and you use the GET endpoint to track progress.

Endpoints are nested under a project's forecast:

POST /v1/projects/:projectId/forecasts/:forecastId/run
GET  /v1/projects/:projectId/forecasts/:forecastId/run/:jobId

---

Triggering a Run

POST /v1/projects/:projectId/forecasts/:forecastId/run

Submits an asynchronous forecast run. Returns 202 Accepted immediately with a jobId.

Path Parameters

Parameter	Description
projectId	ObjectId of the project containing the forecast
forecastId	ObjectId of the forecast to run

Request Body

The request body is optional. When omitted, the run uses the default forecast settings.

Field	Type	Required	Description
configurationId	string | null	No	ObjectId of a saved forecast configuration to apply. Must be the same forecastType as the forecast.
settings	object	No	Runtime settings override applied on top of the resolved configuration. See Settings Override.

Settings Override

The settings object accepts the same shape as the ForecastConfigurationSettings sub-object — the writable, non-metadata portion of a saved configuration. When both configurationId and settings are provided, the explicit settings values take precedence over the saved configuration.

Field	Type	Description
automaticForecast	object	Stream configuration override. See automaticForecast in the Forecast Configurations reference.
forecastScope	object	Scope flags: { auto: boolean, proximity: boolean }. Note: proximity: true is not supported via this endpoint.
resolution	string	Production data resolution. One of "monthly_only", "monthly_preference", "daily_only", "daily_preference".
overwriteManual	boolean	When true, the run will overwrite existing manual forecasts.

For the full field definitions, validation rules, and enum values for automaticForecast (including streamConfigurations, timeDict, weightDict, wellLifeDict, matchEur, and modelParameters), see the Forecast Configurations reference.

Response

202 Accepted

{
  "jobId": "64b3c2f1a9e34d0012abc123"
}

Use the jobId to poll for run status.

---

Polling Run Status

GET /v1/projects/:projectId/forecasts/:forecastId/run/:jobId

Returns the current status of a forecast run. The jobId is scoped to the forecastId in the URL — you cannot poll a job that belongs to a different forecast.

Path Parameters

Parameter	Description
projectId	ObjectId of the project
forecastId	ObjectId of the forecast
jobId	Job ID returned by the POST endpoint

Response

200 OK

Field	Type	Description
jobId	string	The job identifier
status	string	Current run status. See Status Values.
progress	number	Completion percentage, 0–100
createdAt	string | null	ISO datetime when the job was created
startedAt	string | null	ISO datetime when execution began
completedAt	string | null	ISO datetime when the job completed (success or failure)
result	object | null	Result payload when the run completed successfully
error	string | null	Error message when the run failed

Status Values

status	Meaning
"pending"	The job is queued and waiting to start
"running"	The job is actively processing
"successful"	The run completed without errors
"failed"	The run encountered an error (see error field)

---

Limitations and Constraints

Concurrent Run Limit

A maximum of 5 forecast runs submitted by the api may be in progress simultaneously per tenant. Submitting a run when this limit is reached returns 429 Too Many Requests.

One Run Per Forecast

A forecast may only have one run in progress at a time. Attempting to start a second run while one is already running returns 409 Conflict.

Proximity Forecasting Not Supported

The forecast run API does not support proximity forecasting. If the resolved configuration has forecastScope.proximity: true, the request is rejected with 400 Bad Request. This applies whether proximity is set in a saved configuration (configurationId) or in the request settings.

Wells Required

The forecast must have at least one well assigned. Attempting to run a forecast with no wells returns 400 Bad Request.

Stream Restrictions

The streams specified in automaticForecast.streamConfigurations must be a subset of the streams allowed for the forecast:

• If the forecast has a stream assignment, only streams declared in that assignment are permitted.
• If the forecast has no stream assignment, only the standard phases — "oil", "gas", and "water" — are permitted.

Requesting a stream that is not allowed returns 400 Bad Request.

Configuration Type Match

When configurationId is provided, its forecastType must match the forecast's type (deterministic or probabilistic). A mismatch returns 400 Bad Request.

---

Error Reference

HTTP Status	Condition
400	Validation error in request body (see field-level error details in response)
400	Proximity forecasting requested (forecastScope.proximity: true)
400	Streams in the configuration are not allowed for this forecast
400	configurationId type does not match the forecast type
400	The forecast has no wells
404	forecastId or projectId not found
404	configurationId not found or does not belong to this tenant
404	jobId not found, or does not belong to the specified forecastId
409	The forecast already has a run in progress
429	Tenant concurrent forecast run limit (5) reached

---

Examples

Run with a saved configuration

POST /v1/projects/5e5981b9e23dae0012624d72/forecasts/61a4d175f1da1800136c4b21/run
{
  "configurationId": "64b1c0faa9e34d0012a11111"
}

Run with a runtime settings override

POST /v1/projects/5e5981b9e23dae0012624d72/forecasts/61a4d175f1da1800136c4b21/run
{
  "settings": {
    "resolution": "monthly_only",
    "overwriteManual": true,
    "automaticForecast": {
      "streamConfigurations": [
        {
          "streams": ["oil"],
          "configuration": {
            "axisCombo": "rate",
            "peakPreference": "auto",
            "peakSensitivity": "mid",
            "internalFilter": "none",
            "timeDict": {
              "mode": "last",
              "numRange": { "min": 3, "max": 24 },
              "unit": "month"
            },
            "weightDict": {
              "mode": "all"
            },
            "wellLifeDict": {
              "wellLifeMethod": "duration_from_last_data",
              "num": 30,
              "unit": "year"
            },
            "matchEur": {
              "matchType": "no_match"
            },
            "modelParameters": {
              "modelName": "arps_modified_wp",
              "b": { "min": 0.5, "max": 1.5 },
              "D_eff": { "min": 1, "max": 99 },
              "D_lim_eff": 8,
              "enforce_sw": true
            }
          }
        }
      ]
    }
  }
}

Run with a configuration and a partial override

POST /v1/projects/5e5981b9e23dae0012624d72/forecasts/61a4d175f1da1800136c4b21/run
{
  "configurationId": "64b1c0faa9e34d0012a11111",
  "settings": {
    "overwriteManual": true
  }
}

Run with default settings (no body)

POST /v1/projects/5e5981b9e23dae0012624d72/forecasts/61a4d175f1da1800136c4b21/run

Poll for status

GET /v1/projects/5e5981b9e23dae0012624d72/forecasts/61a4d175f1da1800136c4b21/run/64b3c2f1a9e34d0012abc123

Response (running):

{
  "jobId": "64b3c2f1a9e34d0012abc123",
  "status": "running",
  "progress": 42,
  "createdAt": "2024-07-16T14:00:00.000Z",
  "startedAt": "2024-07-16T14:00:05.000Z"
}

Response (successful):

{
  "jobId": "64b3c2f1a9e34d0012abc123",
  "status": "successful",
  "progress": 100,
  "createdAt": "2024-07-16T14:00:00.000Z",
  "startedAt": "2024-07-16T14:00:05.000Z",
  "completedAt": "2024-07-16T14:02:37.000Z"
}