Plans and wells
Find existing wells, describe drawn wells, and run, read, save and delete development plans.
A plan forecasts many drawn wells as one background job and stores the result.
Model sets and the dataset
Section titled “Model sets and the dataset”A model set is one basin’s dataset with its oil, gas and water models.
GET /model-setslists your company’s sets, the default first. Sendmodel_set=<id>on any dataset call; without it, the default set answers.- A plan or export stays in its set, so later calls on it need no
model_set. GET /datasetgives the set’sas_ofdate,ip_days, whether EUR and bands are available, andlimitssuch aslimits.forecast_wellsandlimits.plan_wells.GET /formationslists the formations.include=targetmarks the target zones, where you can plan a well.
Existing wells
Section titled “Existing wells”| Call | Returns |
|---|---|
GET / |
Wells for a map. format= with bbox, formation, q (name or key), operator or near and a small limit returns a page of points |
GET / |
One well’s header, by wellbore key |
GET / |
Its production history |
GET / |
Its spacing neighbors |
GET / |
The spacing features the models read for it |
GET / |
The model’s stored prediction beside its actuals |
POST / |
Wells inside a unit’s outline, with an optional buffer |
GET / |
Counts by operator, formation or county, and a numeric field’s spread |
POST / |
A type curve of existing wells’ production: counts, mean and quantiles by day |
Ask for the least data that answers the question.
Drawn wells
Section titled “Drawn wells”A drawn well is a well you plan, in the same shape for POST /forecasts, POST /plans and exports.
| Field | Required | Meaning |
|---|---|---|
shl |
yes | Surface hole location, [lng, |
bhl |
yes | Bottom hole (toe), [lng,. The lateral runs from heel, else shl, to bhl: 100 to 50,000 ft |
heel |
no | Where the lateral starts, when not at shl |
formation |
to forecast | Target formation, from GET / |
tvd_, landing_ or landing_ |
no | Landing. Blank estimates TVD from the structure grid and nearby wells |
til_ |
no | First production date, YYYY-MM-DD. Orders parents and children in spacing |
fluid_, proppant_ |
no | This well’s completion, over the design’s |
pad, scenario |
no | Groups wells by pad. A scenario’s wells never space against another scenario’s |
name |
no | 1 to 60 characters |
These calls lay wells out for you, ready for a plan:
| Call | Does |
|---|---|
POST / |
Fills a polygon at a spacing and azimuth |
POST / |
Reads unit outlines from a zipped shapefile, GeoJSON, KML or KMZ |
POST / |
Fills a whole file of areas |
POST / |
Reads a well inventory file |
Run a plan
Section titled “Run a plan”POST /plans returns the plan and its id at once. Read it with GET /plans/{id}?wait=25: each call returns as soon as
the status changes from running to done or error, or after 25 seconds.
curl -sS --fail-with-body -X POST \ -H "Authorization: Bearer $NOVI_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "name": "Hawk unit infill", "wells": [ {"name": "Hawk 14-1H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-03-01"}, {"name": "Hawk 14-2H", "shl": [-101.928, 31.93], "bhl": [-101.928, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-04-01"} ], "designs": [ {"name": "Recent median"}, {"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000} ], "eur": true }' \ "$NOVI_API_BASE/plans"
# The answer has the plan's id. Each GET with wait=25 returns when the status changes, or after 25 s.PLAN_ID="<the id from the response>"curl -sS --fail-with-body \ -H "Authorization: Bearer $NOVI_API_TOKEN" \ "$NOVI_API_BASE/plans/$PLAN_ID?wait=25"import osimport uuid
import requests
BASE = os.environ["NOVI_API_BASE"]session = requests.Session()session.headers["Authorization"] = f"Bearer {os.environ['NOVI_API_TOKEN']}"
body = { "name": "Hawk unit infill", "wells": [ {"name": "Hawk 14-1H", "shl": [-101.93, 31.93], "bhl": [-101.93, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-03-01"}, {"name": "Hawk 14-2H", "shl": [-101.928, 31.93], "bhl": [-101.928, 31.957], "formation": "WOLFCAMP A", "til_date": "2027-04-01"}, ], "designs": [ {"name": "Recent median"}, {"name": "Upsized", "fluid_bbl_per_ft": 60, "proppant_lb_per_ft": 3000}, ], "eur": True,}r = session.post(f"{BASE}/plans", json=body, headers={"Idempotency-Key": str(uuid.uuid4())}, timeout=60)r.raise_for_status()plan = r.json()
while plan["status"] == "running": r = session.get(f"{BASE}/plans/{plan['id']}", params={"wait": 25}, timeout=60) r.raise_for_status() plan = r.json()
if plan["status"] == "error": raise SystemExit(plan["error"])
for total in plan["totals"]: design = plan["designs"][total["design"]]["name"] oil_eur = total.get("eur", {}).get("oil", {}).get("value") print(design, "wells:", total["wells_with_forecast"], "oil EUR (bbl):", oil_eur)
session.patch(f"{BASE}/plans/{plan['id']}", json={"saved": True}, timeout=60).raise_for_status()The example is in the Midland basin. Take formations and coordinates from your own model set.
The request also takes:
designs: each well is forecast once per design. An empty design takes the recent completions median.eur: trueextends oil and gas forecasts to an EUR.bands: trueadds Low (P10) and High (P90) curves, andband_eur: truean EUR for each, whereGET /datasetsays your set has them.til_dateon the request dates every well that no narrower setting dates. In a dated plan, each planned well’s forecast production is passed to the later wells it is a parent of, where the set’s models read neighbors’ production.depletion_chain: falseturns that off.scenarios,padsandformationsset values per scenario, pad and formation.dry_run: truechecks and counts the plan without starting it.from_plan: <id>reruns a done plan’s request on the set’s current models.
A plan takes up to limits.plan_wells forecasts (wells × designs), up to 50,000. Your queued and running plans share a
cap, limits.plan_unfinished_forecasts: past it, wait for a plan to finish before you start another. See
Errors and limits.
Read a done plan
Section titled “Read a done plan”

| Call | Returns |
|---|---|
GET / |
Status, designs, and totals per design (and per scenario) |
GET / |
Each well’s inputs, TVD, forecasts per design and spacing, paged with limit and cursor. Filter with formation, pad, scenario, q or wells; rank with sort (eur_, cum_ and more) |
GET / |
Histogram and quantiles of a metric across the wells |
GET / |
Oil, gas and water by pad and by landing zone |
GET / |
Wells with inputs outside the models’ training data, by input |
GET / |
Every well’s cumulative curves to EUR. See Forecasts and curves |
GET / |
A well’s drivers per day and the training wells it leans on |
GET / |
A type curve from the plan’s own forecasts |
Keep, share or delete
Section titled “Keep, share or delete”- Unsaved plans are deleted 90 days after they are made.
PATCH /plans/{id}with{"saved": true}keeps one until someone deletes it;{"saved": false}starts a new 90 days.namerenames it. GET /planslists your company’s plans in a model set, newest first, 20 a page by default, up to 100. Filter withq,status,savedandcreated_by=me.POST /plans/{id}/sharesmakes a link to a done plan;DELETE /plans/{id}/shares/{share_id}revokes it.DELETE /plans/{id}stops a running plan or deletes a done one and its shares, leaving no record.unless=saveddeletes it only if it isn’t saved or shared.
Footnotes
Section titled “Footnotes”-
Legacy Forecasts are dynamic imports from Forecast Engine v1. ↩