Skip to content
Developers
Get an API token

Forecasts and curves

Forecast drawn wells in one request, read what a forecast and its curve points mean, and how Novi labels Low and High.

View MarkdownOpen in Claude(opens in a new tab)

A forecast is cumulative oil, gas and water by day on production, for one well and one completion design.

  • Mid (P50) is the point forecast. Without bands, a forecast is Mid alone.
  • Low (P10) and High (P90) are split conformal prediction bands around one well’s forecast. Ask with bands: true; GET /dataset says which streams have them.
  • A plan’s Low total is the sum of its wells’ Low curves, not the plan’s own Low. The same goes for High.
  • The spread across a plan’s wells is well quantiles (q10, q50, q90), not P-levels.

POST /forecasts runs up to 50 drawn wells (limits.forecast_wells) together, spaced against each other and existing wells, once per design, up to 25 designs.

Terminal window
curl -sS --fail-with-body -X POST \
-H "Authorization: Bearer $NOVI_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"wells": [
{"name": "Hawk 14-2H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957], "formation": "WOLFCAMP A"}
],
"designs": [
{"name": "Recent median"},
{"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}
],
"summary": true,
"eur": true,
"ip_days": [360, 720, 1080]
}' \
"$NOVI_API_BASE/forecasts"

Each well returns one forecasts entry per design. Each stream (oil, gas, water) holds:

Field Meaning
unit bbl for oil and water, mcf for gas.
ip_days, values Cumulative volume at each day on production.
eur With eur: true: value, the day it is reached (days) and the decline fit (arps).
bands With bands: true: p10 (Low) and p90 (High), each with its values, and an eur with band_eur: true.
error In place of the above, why this stream has no forecast.
Option Effect
summary: true Each well as a compact summary
ip_days Only the days you list
boe: true BOE (oil plus gas at 6 mcf per bbl) beside the streams
totals: true Totals per design
explain: true Each forecast’s drivers and the training wells it leans on. Up to 10 wells × designs
async: true Runs as a job: read it with GET /forecasts/{id}?wait=25

Every forecast carries checks. Show the flag beside any number from a flagged well.

Check Meaning
out_of_range Inputs outside what the models saw in training
missing Blank inputs the training rarely had blank
flagged Any check applies
  • A curve is cumulative volume at each ip_day, from 0 on day 0, straight from point to point. A period’s volume is the cumulative at its end minus the cumulative at its start.
  • EUR is opt-in: a decline-curve fit that extends the forecast to the EUR day (settings in GET /dataset eur.defaults). It is not a model output.
  • With an EUR, a curve follows the extension to the EUR day, then stays flat. Without one, it ends at its last point.

GET /plans/{id}/curves pages through a done plan’s wells: cumulative volume per stream every 30 days to EUR, the same numbers the monthly export writes.

Parameter Default Meaning
design 0 The design, by its index in the plan’s designs.
streams every stream the plan serves Comma-separated, as oil,gas.
p_levels P50 Comma-separated from P50, P10, P90. Low and High need a plan made with bands.
limit 100 Wells per page, 1 to 200.
cursor next_cursor from the previous page.
start_date til, or a date as YYYY-MM-DD, to add volumes by calendar month.
{
"plan_id": "e287ce51-430c-4871-87c2-e9c4191fb412",
"design": 0,
"step_days": 30,
"streams": ["oil", "gas"],
"p_levels": ["P50"],
"wells": [
{
"index": 0,
"key": "DRAWN-0",
"well_uid": "54a872630fdca9a2660d598fe5467269",
"label": "Plan well 1",
"name": "Hawk 14-2H",
"til_date": "2027-03-01",
"shl": [-101.93, 31.93],
"bhl": [-101.93, 31.957],
"curves": {
"oil": { "unit": "bbl", "P50": { "cum": [18412.35, 33021.8, 45210.06], "model_months": 36, "extension": "arps", "note": null } },
"gas": { "error": "The forecast worker failed: gas model timed out" }
}
}
],
"next_cursor": null
}

The cum array is cut short here. To read a well:

  • cum[m-1] is the cumulative at day 30·m, to 0.01, or null. IP30 is cum[0], IP540 cum[17]; divide by 30·m for the average daily rate.
  • The first model_months points are the model’s, the rest the decline extension. extension is arps, flat or table, or null with a note saying why the curve stops.
  • An unplaced well, a failed stream or a missing band comes back as {"error": "..."} in place of its curves.
  • well_uid (32 characters) is the same on every read of the plan. key is unique within one plan only.
  • Only a done plan has curves. Send a page’s ETag back as If-None-Match to learn that nothing changed.

With start_date, each curve adds calendar: volume per calendar month from first_month (YYYY-MM).

  • start_date=til starts each well at its TIL date, else the plan’s day; start_date_source says which (til, plan_day or request). start_date=YYYY-MM-DD starts every well that day.
  • The first month is partial unless the start is a 1st. The months add up to the last cumulative, within rounding.

POST /declines fits the same EUR decline to cumulative curves you send.

GET /plans/{id}/wells/{index}/explanations/{design} explains one plan well: each input’s contribution per day (SHAP), the training wells it leans on, and, on request, analog wells with their production. An analog spread is a peer range, not Low and High.