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.
A forecast is cumulative oil, gas and water by day on production, for one well and one completion design.
Low, Mid and High
Section titled “Low, Mid and High”- 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 /datasetsays 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.
Forecast drawn wells
Section titled “Forecast drawn wells”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.
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"import os
import requests
BASE = os.environ["NOVI_API_BASE"]session = requests.Session()session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
body = { "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],}r = session.post(f"{BASE}/forecasts", json=body, timeout=120)r.raise_for_status()result = r.json()
for well in result["wells"]: for forecast in well.get("forecasts", []): oil = forecast.get("oil") or {"error": forecast.get("error", "no oil stream")} if "error" in oil: print(well["label"], "design", forecast["design"], "oil failed:", oil["error"]) continue print(well["label"], "design", forecast["design"], dict(zip(oil["ip_days"], oil["values"])), "EUR:", oil.get("eur", {}).get("value"))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_, 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_. |
error |
In place of the above, why this stream has no forecast. |
| Option | Effect |
|---|---|
summary: true |
Each well as a compact summary |
ip_ |
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 / |
Every forecast carries checks. Show the flag beside any number from a flagged well.
| Check | Meaning |
|---|---|
out_ |
Inputs outside what the models saw in training |
missing |
Blank inputs the training rarely had blank |
flagged |
Any check applies |
What a curve means
Section titled “What a curve means”- 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 /dataseteur.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.
Read a plan’s curves
Section titled “Read a plan’s curves”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,. |
p_ |
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_ from the previous page. |
|
start_ |
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, ornull. IP30 iscum[0], IP540cum[17]; divide by 30·m for the average daily rate.- The first
model_monthspoints are the model’s, the rest the decline extension.extensionisarps,flatortable, ornullwith anotesaying 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.keyis unique within one plan only.- Only a done plan has curves. Send a page’s
ETagback asIf-None-Matchto learn that nothing changed.
Calendar months
Section titled “Calendar months”With start_date, each curve adds calendar: volume per calendar month from first_month (YYYY-MM).
start_date=tilstarts each well at its TIL date, else the plan’s day;start_date_sourcesays which (til,plan_dayorrequest).start_date=YYYY-MM-DDstarts 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.
Curves you already have
Section titled “Curves you already have”POST /declines fits the same EUR decline to cumulative curves you send.
Explanations
Section titled “Explanations”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.