Skip to content
Developers
Get an API token

Plans and wells

Find existing wells, describe drawn wells, and run, read, save and delete development plans.

View MarkdownOpen in Claude(opens in a new tab)

A plan forecasts many drawn wells as one background job and stores the result.

A model set is one basin’s dataset with its oil, gas and water models.

  • GET /model-sets lists your company’s sets, the default first. Send model_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 /dataset gives the set’s as_of date, ip_days, whether EUR and bands are available, and limits such as limits.forecast_wells and limits.plan_wells.
  • GET /formations lists the formations. include=target marks the target zones, where you can plan a well.
Call Returns
GET /wells Wells for a map. format=geojson with bbox, formation, q (name or key), operator or near and a small limit returns a page of points
GET /wells/{key} One well’s header, by wellbore key
GET /wells/{key}/production Its production history
GET /wells/{key}/spacing Its spacing neighbors
GET /wells/{key}/features The spacing features the models read for it
GET /wells/{key}/predictions The model’s stored prediction beside its actuals
POST /wells/search Wells inside a unit’s outline, with an optional buffer
GET /wells/facets Counts by operator, formation or county, and a numeric field’s spread
POST /wells/typecurve A type curve of existing wells’ production: counts, mean and quantiles by day

Ask for the least data that answers the question.

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, lat]
bhl yes Bottom hole (toe), [lng, lat]. 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 /formations
tvd_ft, landing_below_top_ft or landing_fraction no Landing. Blank estimates TVD from the structure grid and nearby wells
til_date no First production date, YYYY-MM-DD. Orders parents and children in spacing
fluid_bbl_per_ft, proppant_lb_per_ft 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 /layouts/fill Fills a polygon at a spacing and azimuth
POST /areas Reads unit outlines from a zipped shapefile, GeoJSON, KML or KMZ
POST /areas/fill Fills a whole file of areas
POST /inventories/read Reads a well inventory file

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.

Terminal window
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"

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: true extends oil and gas forecasts to an EUR. bands: true adds Low (P10) and High (P90) curves, and band_eur: true an EUR for each, where GET /dataset says your set has them.
  • til_date on 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: false turns that off.
  • scenarios, pads and formations set values per scenario, pad and formation.
  • dry_run: true checks 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.

A done plan's Plan Summary in Forecasts: oil at 3 years, oil and BOE EUR, and a table of each well's volumes and EUR.A done plan's Plan Summary in Forecasts: oil at 3 years, oil and BOE EUR, and a table of each well's volumes and EUR.
Sample plan; numbers and timing are illustrative.
Call Returns
GET /plans/{id} Status, designs, and totals per design (and per scenario)
GET /plans/{id}?include=wells 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_boe, cum_oil and more)
GET /plans/{id}/stats Histogram and quantiles of a metric across the wells
GET /plans/{id}/rollup Oil, gas and water by pad and by landing zone
GET /plans/{id}/checks Wells with inputs outside the models’ training data, by input
GET /plans/{id}/curves Every well’s cumulative curves to EUR. See Forecasts and curves
GET /plans/{id}/wells/{index}/explanations/{design} A well’s drivers per day and the training wells it leans on
GET /plans/{id}/typecurve/{design} A type curve from the plan’s own forecasts
  • 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. name renames it.
  • GET /plans lists your company’s plans in a model set, newest first, 20 a page by default, up to 100. Filter with q, status, saved and created_by=me.
  • POST /plans/{id}/shares makes 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=saved deletes it only if it isn’t saved or shared.
  1. Legacy Forecasts are dynamic imports from Forecast Engine v1. ↩