Forecast Configurations API Reference

The Forecast Configurations API lets you create, read, update, and delete saved automatic forecast configurations. These configurations define the stream settings (model parameters, time windows, well life, EUR matching, etc.) that are applied when a forecast is run.

All endpoints are rooted at:

/v1/forecast-configurations

Key Concepts

A forecast configuration is either deterministic or probabilistic. The type is set on creation and cannot be changed.
Deterministic configurations are project-scoped — they require a project field and belong to a single project.
Probabilistic configurations are user-scoped — the project field is prohibited and they are shared across projects for the authenticated user.
PUT (upsert) matches on a natural key: name + project for deterministic, name alone for probabilistic.
On write, missing streamConfigurations fields are filled from defaults based on the chosen model, so stored documents are always complete.
On GET, only fields relevant to the active mode are returned for each dict (e.g. absoluteRange is omitted when timeDict.mode is not "absolute_range").

Endpoints

Method	Path	Description	Limit
`HEAD`	`/v1/forecast-configurations`	Return count headers only	–
`GET`	`/v1/forecast-configurations`	List configurations (paginated)	200/page
`GET`	`/v1/forecast-configurations/:id`	Get a single configuration by ID	–
`POST`	`/v1/forecast-configurations`	Create new configurations	100/call
`PUT`	`/v1/forecast-configurations`	Upsert by natural key	100/call
`PATCH`	`/v1/forecast-configurations`	Partial update by natural key	100/call
`DELETE`	`/v1/forecast-configurations`	Delete by filter	100/call
`DELETE`	`/v1/forecast-configurations/:id`	Delete a single configuration by ID	–

Query Parameters (GET / HEAD)

Parameter	Type	Description
`skip`	number	Records to skip for pagination (default: 0)
`take`	number	Records to return per page (default: 25, max: 200)
`sort`	string	Sort field and direction (e.g. `id`, `-id`)
`cursor`	string	Cursor token from a previous response for cursor pagination
`forecastType`	string	Filter by type: `deterministic` or `probabilistic`
`id`	string	Filter by one or more IDs (comma-separated)
`name`	string	Filter by name
`createdAt`	string	Filter by creation date
`updatedAt`	string	Filter by last-updated date

Top-Level Fields

Field	Type	Writable	Required	Description
`id`	string	No	–	ObjectId of this configuration (read-only)
`name`	string	Yes	Yes	Display name. 1–250 characters. Must be unique per project/type.
`forecastType`	string	Yes	Yes	`"deterministic"` or `"probabilistic"`
`project`	string \| null	Yes	Conditional	ObjectId. Required for `deterministic`; prohibited for `probabilistic`
`createdBy`	string	No	–	ObjectId of the user who created this record (read-only)
`createdByName`	string	No	–	Display name of the creator (read-only)
`isAdmin`	boolean	No	–	Admin flag (read-only; cannot be set via the API)
`resolution`	string	Yes	No	Production data resolution. See Resolution values.
`forecastScope`	object	Yes	No	Forecasting scope flags. See `forecastScope`.
`overwriteManual`	boolean	Yes	No	When `true`, running this configuration will overwrite existing manual forecasts.
`automaticForecast`	object	Yes	No	Core stream configuration. See `automaticForecast`.
`createdAt`	string (ISO)	No	–	Creation timestamp (read-only)
`updatedAt`	string (ISO)	No	–	Last-updated timestamp (read-only)

Resolution Values

Value	Description
`"monthly_only"`	Only generate monthly-resolution forecasts (default)
`"monthly_preference"`	Prefer monthly; fall back to daily if monthly data is unavailable
`"daily_only"`	Only generate daily-resolution forecasts
`"daily_preference"`	Prefer daily; fall back to monthly if daily data is unavailable

`forecastScope`

Controls the scope of wells included when this configuration is applied during a run.

Field	Type	Description
`auto`	boolean	When `true`, automatically includes all wells in the forecast
`proximity`	boolean	Proximity forecasting flag. Note: proximity forecasting is not supported via the forecast run API endpoint.

`automaticForecast`

The main configuration block. Contains an array of stream configuration entries.

Field	Type	Required	Description
`streamConfigurations`	array	No	One or more stream configuration entries. See below.

Stream Configuration Entry

Each entry in streamConfigurations applies a single configuration to one or more production streams (phases).

Field	Type	Required	Description
`name`	string	No	Optional label for this configuration group
`streams`	array of string	Yes	Phases this configuration applies to. Must have at least one element. Each phase must be non-empty and must not appear in any other entry.
`configuration`	object	Yes	The forecast settings for these streams. See Stream Configuration.

Stream uniqueness

A phase (e.g. "oil") may appear in at most one entry's streams array — both within a single entry and across all entries. Duplicate phases in the same request are rejected with HTTP 400.

Standard phases are "oil", "gas", and "water". Custom streams may also be used if configured for the forecast.

Stream Configuration

The configuration object within each stream entry holds all the settings that drive the automatic forecasting algorithm.

Core Fields

Field	Type	Description
`axisCombo`	string	Forecast axis type: `"rate"` or `"ratio"`
`basePhase`	string \| null	Required when `axisCombo` is `"ratio"`. The base phase for the ratio calculation (e.g. `"oil"`, `"gas"`).
`dispersion`	number	Dispersion parameter for probabilistic fitting
`flatForecastThres`	number	Threshold for triggering flat forecast detection
`internalFilter`	string	Data filtering level: `"none"`, `"low"`, `"mid"`, `"high"`, `"very_high"`
`internalFilterAll`	boolean	When `true`, applies `internalFilter` to all data points
`lowDataThreshold`	number \| null	Minimum number of data points required before switching to a low-data forecast
`movingAverageDays`	number \| null	Window size (in days) for smoothing input production data
`peakPreference`	string	How the peak rate is selected: `"start_point"`, `"last"`, `"max"`, `"end_flat"`, `"auto"`
`peakSensitivity`	string	Sensitivity of the peak-detection algorithm: `"low"`, `"mid"`, `"high"`
`percentile`	array of number	Target percentile values for probabilistic forecasts (e.g. `[10, 50, 90]`)
`percentileRange`	object	Allowed range of output percentiles: `{ min, max }`. `min` < `max`, `max` ≤ 100.
`probPara`	array of string	Probabilistic parameters to fit
`qFinal`	number	Terminal rate (economic limit) for the decline curve
`remove0`	boolean	When `true`, removes zero-value production data points before fitting
`shortProdThreshold`	number \| null	Well is flagged as "short production" if its data length is below this threshold
`useLowDataForecast`	boolean	When `true`, use an alternative algorithm for wells with limited data
`useMinimumData`	boolean	When `true`, use only the most recent data window for fitting
`validIdx`	number \| null	Index of the last valid data point to include in the fit
`valueRange`	object	Allowed range for rate values: `{ min, max }`. `min` < `max` (strict).
`timeDict`	object	Training data time window. See `timeDict`.
`weightDict`	object	Data weighting window. See `weightDict`.
`wellLifeDict`	object	Well life / production cutoff settings. See `wellLifeDict`.
`matchEur`	object	EUR matching settings. See `matchEur`.
`modelParameters`	object	Model-specific parameters. See `modelParameters`.

`timeDict`

Defines the time window of production data used to fit the decline curve.

Field	Type	Description
`mode`	string	Window selection mode. See table below.
`unit`	string	Time unit (e.g. `"month"`, `"year"`)
`absoluteRange`	object	`{ min, max }` — ISO date strings. `min` ≤ `max`. Required when `mode` is `"absolute_range"`; must not be provided otherwise.
`headerRange`	object	`{ min, max }` — header date strings. Required when `mode` is `"header_range"`; must not be provided otherwise.
`numRange`	object	`{ min, max }` — number of time units. `min` ≤ `max`. Used when `mode` is `"first"`, `"last"`, or `"all"`; must not be provided with date-based modes.

`mode` value	Meaning
`"first"`	Use the first N time units of production data (`numRange`)
`"last"`	Use the last N time units of production data (`numRange`)
`"all"`	Use all available production data
`"absolute_range"`	Use data between two specific calendar dates (`absoluteRange`)
`"header_range"`	Use data relative to a header date (`headerRange`)

Mode-exclusive fields

Only the range object for the active mode should be provided. For example, when mode is "absolute_range", include absoluteRange but omit numRange and headerRange. The API returns 400 if an incompatible range object is sent with its mode.

`weightDict`

Defines how production data points are weighted during the fitting process.

Field	Type	Description
`mode`	string	Weighting mode. `"absolute_range"` or other mode values (e.g. `"all"`, `"first"`, `"last"`)
`unit`	string	Time unit for range-based weighting
`value`	number	Weighting multiplier
`absoluteRange`	object	`{ min, max }` — ISO date strings. `min` ≤ `max`. Required when `mode` is `"absolute_range"`; must not be provided otherwise.
`numRange`	object	`{ min, max }` — number of time units. `min` ≤ `max`. Used when `mode` is not `"absolute_range"`; must not be provided with absolute range mode.

weightDict.mode casing

The API always returns "absolute_range" (snake_case) in GET responses. Both "absolute_range" and "absoluteRange" are accepted on write; the value is stored internally as "absoluteRange" for UI compatibility.

`wellLifeDict`

Defines when a well is considered to have reached the end of its productive life.

Field	Type	Description
`wellLifeMethod`	string	Cutoff method. See table below.
`fixedDate`	string \| null	ISO date string. Required when `wellLifeMethod` is `"fixed_date"`; must not be provided otherwise.
`num`	number	Duration length (positive). Required (and must be > 0) when `wellLifeMethod` is not `"fixed_date"`; must not be provided when `"fixed_date"`.
`unit`	string	Duration unit (e.g. `"year"`, `"month"`). Used with duration-based methods.

`wellLifeMethod` value	Meaning
`"duration_from_first_data"`	`num` units after the first production data point
`"duration_from_last_data"`	`num` units after the last production data point
`"duration_from_today"`	`num` units from today
`"fixed_date"`	A specific calendar date (`fixedDate`)

`matchEur`

Controls whether and how the forecast is constrained to match a target EUR (Estimated Ultimate Recovery).

Field	Type	Description
`matchType`	string	Matching mode. See table below.
`matchForecastId`	string \| null	ObjectId of the reference forecast. Required when `matchType` is `"forecast"`; must not be provided for other types.
`matchPercentChange`	number	Allowed percent deviation from the reference EUR. Required when `matchType` is `"forecast"`; must not be provided for other types.
`matchEurNum`	number	Target EUR value. Required when `matchType` is `"number"`; must not be provided for other types.
`errorPercentage`	number	Acceptable error tolerance (percent). Required when `matchType` is `"forecast"` or `"number"`.

`matchType` value	Meaning
`"no_match"`	No EUR matching — forecast runs unconstrained
`"forecast"`	Match EUR of another forecast (`matchForecastId`) within `matchPercentChange`%
`"number"`	Match a specific EUR value (`matchEurNum`) within `errorPercentage`%

Field exclusivity

Fields from one matchType must not be provided for another. For example, matchEurNum is rejected when matchType is "forecast", and matchForecastId is rejected when matchType is "number".

`modelParameters`

Model-specific fitting parameters. The modelName field is required whenever modelParameters is provided; all other keys depend on the chosen model.

Field	Type	Description
`modelName`	string	Required. The forecast model to use. Must be a valid model name from the ComboCurve form templates.
`b`	object	`{ min, max }` — Arps b-exponent range
`b2`	object	`{ min, max }` — Secondary b-exponent range (multi-segment models)
`c`	object	`{ min, max }` — Ratio/flat model parameter range
`D_eff`	object	`{ min, max }` — Effective decline rate range (% per year)
`D2_eff`	object	`{ min, max }` — Secondary effective decline rate range
`D_lim_eff_range`	object	`{ min, max }` — Effective terminal decline rate range
`minus_t_decline_t0`	object	`{ min, max }` — Time offset from t₀ to decline start
`minus_t_elf_t_peak`	object	`{ min, max }` — Time from peak to end of linear flow
`minus_t_peak_t0`	object	`{ min, max }` — Time from t₀ to peak
`minus_t1_t_peak`	object	`{ min, max }` — Time from peak to t₁ (multi-segment)
`q_end`	object	`{ min, max }` — Terminal rate range
`q_peak`	object	`{ min, max }` — Peak rate range
`q_start`	object	`{ min, max }` — Starting rate range
`t_linear_duration`	object	`{ min, max }` — Linear flow duration range
`D_lim_eff`	number \| null	Effective terminal decline rate (scalar)
`b_prior`	number \| null	Prior for the b-exponent in Bayesian fitting
`b_strength`	string \| null	Strength of the b prior: `"None"`, `"Low"`, `"Medium"`, `"High"`
`enforce_sw`	boolean	Enforce Schwarzkopf well analysis constraints

Model validation

modelName must be compatible with the axisCombo (some models are ratio-axis only)
Each parameter value must fall within the hard bounds declared for that model

Validation Rules Summary

Rule	Detail
`name` length	1–250 characters
`forecastType: "deterministic"`	`project` is required
`forecastType: "probabilistic"`	`project` must not be provided
Stream uniqueness	Each phase may appear in at most one `streamConfigurations` entry
`streams` non-empty	Each entry must have at least one stream
`axisCombo: "ratio"`	`basePhase` is required
`percentileRange`	`min` < `max`, `max` ≤ 100
`valueRange`	`min` < `max` (strict)
`timeDict`	Mode-exclusive range fields; date ranges must be ordered
`weightDict`	Mode-exclusive range fields; date ranges must be ordered
`wellLifeDict`	`num` required and positive for duration methods; `fixedDate` required for `"fixed_date"`
`matchEur`	Field presence tied to `matchType`; fields from other types are rejected
`modelParameters`	Valid `modelName` required; parameter keys and values validated against model definition
`isAdmin` / `userDefault`	These fields are read-only and cannot be set via the API

Examples

Create a deterministic configuration

POST /v1/forecast-configurations
[
  {
    "name": "My Arps Config",
    "forecastType": "deterministic",
    "project": "5e5981b9e23dae0012624d72",
    "resolution": "monthly_only",
    "overwriteManual": false,
    "automaticForecast": {
      "streamConfigurations": [
        {
          "name": "Oil stream",
          "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
            }
          }
        },
        {
          "streams": ["gas", "water"],
          "configuration": {
            "axisCombo": "rate",
            "peakPreference": "auto",
            "peakSensitivity": "mid",
            "internalFilter": "none",
            "timeDict": {
              "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
            }
          }
        }
      ]
    }
  }
]

Create a probabilistic configuration with absolute date range

POST /v1/forecast-configurations
[
  {
    "name": "Probabilistic Shale Config",
    "forecastType": "probabilistic",
    "resolution": "monthly_only",
    "automaticForecast": {
      "streamConfigurations": [
        {
          "streams": ["oil"],
          "configuration": {
            "axisCombo": "rate",
            "peakPreference": "auto",
            "peakSensitivity": "mid",
            "percentile": [10, 50, 90],
            "timeDict": {
              "mode": "absolute_range",
              "absoluteRange": { "min": "2020-01-01", "max": "2024-12-31" }
            },
            "weightDict": {
              "mode": "absolute_range",
              "absoluteRange": { "min": "2022-01-01", "max": "2024-12-31" }
            },
            "wellLifeDict": {
              "wellLifeMethod": "fixed_date",
              "fixedDate": "2055-01-01"
            },
            "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
            }
          }
        }
      ]
    }
  }
]

Key Concepts​

Endpoints​

Query Parameters (GET / HEAD)​

Top-Level Fields​

Resolution Values​

forecastScope​

automaticForecast​

Stream Configuration Entry​

Stream Configuration​

Core Fields​

timeDict​

weightDict​

wellLifeDict​

matchEur​

modelParameters​

Validation Rules Summary​

Examples​

Create a deterministic configuration​

Create a probabilistic configuration with absolute date range​