Compare plans, scenarios or a forecast source
Compares two sides, each a done plan's wells under one design (design, 0 by default) or one scenario's (scenario), in one model set.
Compare plans, scenarios or a forecast source
/comparisonsCompares two sides, each a done plan's wells under one design (design, 0 by default) or one scenario's (scenario), in one model set. Both sides may be the same plan. Nothing is stored and no model worker runs.
Sides
A plan made with scenarios compares one scenario at a time, since its totals don't add alternatives. Each side echoes what it is and what made it (ComparisonSideEcho); a plan whose stored record can't be read echoes this server's release and the model set the request reached.
Numbers
Every number is one GET /plans/{id} or its stats already serve: a scenario side's EUR equals that plan's totals for its scenario and design, and its cumulative at ip_day the summed forecast curve's value there (BOE: the forecast.boe total GET /plans/{id}?boe=true serves, over the wells with both oil and gas forecasts); its distribution equals GET /plans/{id}/stats' group_by=scenario row for it. Quantiles are of each side's wells' values (q10 the 10th-percentile well), not P-level bands. totals has water's EUR too when both sides fit it, and each row its unit and each side's well count.
deltais b − a, rounded to 0.1.delta_pctis (b − a) / a × 100, rounded to 0.01; null when a is 0 or either value is null.- Swapping the sides negates every
deltaexactly, and a side compared with itself gives 0 wherever both sides have a value.
Metric and groups
metric, ip_day and group_by work as ComparisonRequest describes them, and groups as Comparison describes it. An eur_ metric on a side made without eur: true is a 400 naming the side. In a group row, a side without the key is null, and so is the row's delta. Grouping by pad when neither side's plan names pads is a 400 on group_by naming both plans, with details.side a: send wells[].pad.
Curves
include: ["curves"] adds each side's summed curve for the metric's stream by ip_day (BOE over the wells with both oil and gas forecasts), cumulative and each step's average daily rate. With bands too, each side's summed P10 and P90 cumulative where its plan was made with bands (Novi's P10 is the low curve; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan).
Warnings
warnings give a code and a sentence when the sides differ in model set, in models (the same set with a changed manifest or pins), in release or in EUR settings; when one side has no EUR (the EUR rows are left out); when a side's wells lack forecasts; and when a side has no bands that bands asked for.
Pairing wells
pair pairs the sides' wells and adds pairs: the method used, how many paired, and each side's unpaired wells. ComparisonPairing lists the methods.
auto, the default, pairs by name when every well on both sides has a realname(a default label such as Plan well 3 never counts) and no name repeats on a side, else by location.locationpairs each well once, the same formation first, so stacked benches pair within their bench.namepairs a repeated name's wells by location within it, with aduplicate_nameswarning.- Location pairing examines at most 64 nearby wells per well. Wells packed closer, as many on one spot, are a 400 naming
pair: pair them byindexormap.
Paired wells
include: ["wells"] (pairing by auto when pair is absent) adds wells: a page of rows, one per pair, with each side's value, delta and delta_pct, in wells.sort order; and a summary over every pair: the count, each pair's delta_pct (sorted values under 20 pairs, else a histogram), its q10, q50 and q90 (quantiles of pairs, not P-levels) and left_out. When side a's plan has band_eur and the metric is an EUR, each row's band_position places side b's value in side a's P10 to P90 EUR, counted in summary.band; otherwise a no_band_position warning.
Changed inputs
include: ["inputs"] adds inputs.changed: each input that differs on any pair (ComparisonInputChange lists them), how many pairs, and the typical change: b − a, the median among pairs with both values, or for formation the most common change.
Horizon
horizon: { "years": n } (1 to 50, EUR on both sides) adds cumulative oil, gas and BOE rows, with horizon_years, at ip_day the last 30-day step within n × 365 days. Each well counts its forecast, then its EUR curve as eur_curve=month gives it, then past its EUR day its EUR.
Calendar curves
align: "calendar" (with include: ["curves"], and a well with a TIL date on each side) adds curves.calendar: each side's summed curve by month start, as GET /plans/{id} totals.by_date sums a plan's, with each step's average daily rate.
A forecast source
Either side may be { "source": "<id>" } (POST /forecast-sources) when the other is a plan; two sources are a 400.
- The source is read as you: a private one is a 404 naming the side to another user, a share link's viewer or another tenant. Without a state store a source side is a 409.
reserves_categoryis required on a source holding more than one (a 400 lists them with their curve counts); Novi's P-levels never stand in for one.- Each well under it runs through its decline profile (GET /conventions?include=decline_profiles), each stream from day 0 at its curve's start date (a constants ratio at its parent stream's).
- From those runs come each EUR, to its curve's limit or end date, the cumulatives at
ip_dayandhorizon, the spread over its wells, and its summed curve on the plan side's ip_days. - A source has no bands. Its numbers are in bbl, mcf and BOE whatever the file's units.
- A source whose wells would take more than 120,000,000 steps of decline-curve work (a day a curve steps through, or a day measured) is a 400 on the side naming its wells and curves: save the wells you need as a smaller source.
align: "calendar"runs to the first month start on or after its last stream start plus 1,080 days, each well held at its last cumulative. It needs a start date on every well (a Novi arps.csv has none: a 400) and at most 1,200 month starts (a 400 names the earliest and latest start).
Pairing a source
On a source side:
autouses the pairs saved on the source when it links to this plan, elsenamewhen that pairs a well, elseuwi.saveduses only the saved pairs (a 400 when there are none).namematches a source Well ID to a plan well's real name, trimmed and ignoring case;uwidoes the same without dashes, spaces and dots.maptakes Well IDs on the source side.location,index,tolerance_ft,group_by,normalize_lateral_ftandinclude: ["inputs"]are 400s: a source has no locations, order, designs, formations, scenarios, pads, laterals or inputs.- Its unpaired wells and rows name Well IDs (
a_well_id,b_well_id);band_positionapplies with the plan as side a.
Source warnings
gas_basis_differs (a sales-gas source), conventions_differ (any profile but novi's), horizons_differ (the EURs end at different days) and source_unpaired.
Value
include: ["value"] prices each side as POST /economics prices one scenario, under one deck and conventions (deck_id, deck and conventions, each a 400 without it), and adds value with the difference.
- A plan side prices its wells under its design as a plan reference does: its
economicsandbreakevenequal POST /economics withscenarios: [{"plan": {id, design, scenario}}]andinclude: ["breakeven"]. - A plan side needs a plan made with
eur: true(a 400 naming the side); more than 50 wells are priced as one pad. - A forecast source side prices only its wells that pair with a plan well (by
autowhenpairis absent): the plan well's lateral and completions under the plan side's design, with the source well's own cumulatives on the plan side's ip_days and its EURs, to the later EUR day (eur_days). - An unpaired source well is listed in
unpricedwith a reason. When both sides price different counts, avalue_wells_differwarning names them. - A side with any priced well it can't give a cash flow (a source well without water, say) has
economicsnull and areasonnaming the first. deltais b − a for capex, npv, irr_pct, payback_months and each breakeven price, to 0.01; null where either side has none.
Value limits
Both sides together may hold at most 5,000 wells (a source side's under its reserves category) and 5,000,000 well-months: each well's 30-day months to its EUR day (a source well's eur_days may pass POST /economics' 60 years), or to its curve's last ip_day if later. Past either is a 400 on include naming each side's count, before anything is priced: price larger sides with POST /economics in scenarios of up to 50 wells, or compare fewer wells.
Errors
A request whose sides are plans of two model sets is a 400 naming each side's set: compare plans of one set. A missing plan, another tenant's or one on a model set you can't use is a 404, as GET /plans/{id} answers; a running or failed plan is a 409.
Parameters
Query parameters
model_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches the base dataset; once the server retires it, a 400 naming the set answering instead.- An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in
details.allowed(published sets only oncedefaultis retired); a set that can't load, a 503 with the reason. - Plans and exports stay in their set: a call naming them (by path,
plan,ids,source.plan, a scenario'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Request body
application/json
The two sides and what to measure.
aobjectRequiredSide a, the base:
deltais b − a anddelta_pctis relative to it. A plan side, or a forecast source side when side b is a plan.ShowHide 2 variants
Any of
ComparisonSide object
One side: a plan's wells under one design, or one scenario's.
planstringRequiredFormat
uuidA done plan's id, as POST /plans returns it.
scenariostringOptional1 to 60 characters
On a plan made with scenarios, the scenario to compare, exactly as its
scenarioslist it; required there, and a 400 on a plan without scenarios. A name it doesn't have is a 400 whosedetails.scenarioslists them.designintegerOptionalDefault
0≥ 0The design, as its index in the plan's
designs; 0 by default. One past the last is a 400.
ComparisonSourceSide object
A forecast source as one side; the other side is a plan. Any other field is a 400 listing these.
sourcestringRequiredFormat
uuidA forecast source's id, as POST /forecast-sources returns it; one you can read.
reserves_categorystringOptionalat least 1 characters
The reserves category to compare, exactly as GET /forecast-sources/{id}
reserves_categorieslists it; required when the source holds more than one.
bobjectRequiredSide b. It may be the plan of side a, with another scenario or design, or a forecast source when side a is a plan.
ShowHide 2 variants
Any of
ComparisonSide object
One side: a plan's wells under one design, or one scenario's.
planstringRequiredFormat
uuidA done plan's id, as POST /plans returns it.
scenariostringOptional1 to 60 characters
On a plan made with scenarios, the scenario to compare, exactly as its
scenarioslist it; required there, and a 400 on a plan without scenarios. A name it doesn't have is a 400 whosedetails.scenarioslists them.designintegerOptionalDefault
0≥ 0The design, as its index in the plan's
designs; 0 by default. One past the last is a 400.
ComparisonSourceSide object
A forecast source as one side; the other side is a plan. Any other field is a 400 listing these.
sourcestringRequiredFormat
uuidA forecast source's id, as POST /forecast-sources returns it; one you can read.
reserves_categorystringOptionalat least 1 characters
The reserves category to compare, exactly as GET /forecast-sources/{id}
reserves_categorieslists it; required when the source holds more than one.
metricstringOptionalThe per-well metric distribution, groups and curves measure: eur_boe by default when both sides have EUR, else cum_boe.
Per-well metrics:
eur_oil(bbl),eur_gas(mcf) andeur_boe(BOE) are each well's EUR and need a plan made witheur: true(400 otherwise);cum_oil,cum_gasandcum_boeare the forecast's cumulative volume atip_day. BOE is oil + gas / 6, only for wells with both."eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"ip_dayintegerOptional≥ 1
For a cum_ metric, the ip_day to measure, one of the forecast ip_days GET /dataset lists; 1080 by default. With an eur_ metric it is a 400.
normalize_lateral_ftnumberOptional≥ 100, ≤ 20000
Scale each well's value to this lateral length in distribution and groups, as GET /plans/{id}/stats does: value × normalize_lateral_ft / its lateral_length_ft. Totals and curves stay unscaled. 100 to 20,000.
group_bystringOptionalAlso compare each group of wells: design (every design index either side has), formation (each well's target formation, null for none), scenario (a 400 when neither side's plan has scenarios), or pad (the pad key, null for wells without one; 400 when neither plan has keys). Pads pair by key in side a plan order then new side b keys, null last, without a cap or Other row.
"design""formation""scenario""pad"includearray of stringsOptionalOptional parts. Any other value is a 400 listing these.
"curves""bands""wells""inputs""value"pairobjectOptionalHow to pair the sides' wells; adds pairs to the answer.
ShowHide 3 child fields
bystringOptionalDefault
"auto"auto (default): name when every well on both sides has a real name and none repeats on a side, else location; with a forecast source side, saved, else name, else uwi.
- name: names found once on each side; a repeated name's wells pair by location within it.
- location: heel and bottom hole each within tolerance_ft; same formation first, then closest, then nearest TVD; one to one.
- index: by position, with a warning.
- map: the pairs in map.
- uwi and saved: forecast source sides only; location and index: plan sides only.
"auto""name""location""index""map""uwi""saved"tolerance_ftnumberOptionalDefault
300≥ 1, ≤ 5280With auto or location: how far apart, ft, a pair's heels (else surface holes) and bottom holes may each be; 300 by default. With another by it is a 400.
maparray of arraysOptionalItems 2 items
With by map, and only then: the pairs, each well once; an index or Well ID outside its side's wells or used twice is a 400 naming the entry (pair.map[k]).
wellsobjectOptionalPaging for the per-well rows; needs include wells (a 400 without).
ShowHide 4 child fields
limitintegerOptionalDefault
100≥ 1, ≤ 1000Rows a page: 1 to 1,000, 100 by default.
cursorstringOptionalwells.next_cursor from the previous page, with the same request otherwise.
sortstringOptionalDefault
"abs_delta"abs_delta (default): the size of delta; delta: delta itself; a_index: side a's well index (a forecast source side a: its file order). Rows without the value go last; ties in side a's order.
"abs_delta""delta""a_index"orderstringOptionaldesc by default for abs_delta and delta, asc for a_index.
"asc""desc"
horizonstring or objectOptionalEach side's cumulative at a common horizon beside its EUR; needs EUR on both sides (a 400 naming the side without).
ShowHide 2 variants
Any of
own: each side's EUR only, the default string
own: each side's EUR only, the default.
"own"Option 2 object
A common horizon: cumulative rows at that many years.
yearsintegerRequired≥ 1, ≤ 50
Years.
alignstringOptionalcalendaradds curves.calendar, each side's curve by calendar month (needs include curves and a well with a TIL date on each side, or a start date on every well of a forecast source side); months_on, the default, adds nothing."months_on""calendar"deck_idstringOptionalWith include value (a 400 without it): the deck to price both sides with, as POST /economics takes it; left out, the set's default deck.
"prototype-midland-flat""house-70-3""illustrative-haynesville-gas"deckobjectOptionalWith include value (a 400 without it): overrides of the deck's values, each within its range, as POST /economics takes them.
ShowHide 20 child fields
oil_pricenumberOptional≥ 0, ≤ 300
$/bbl; 75 in the illustrative Midland deck.
oil_differentialnumberOptional≥ -50, ≤ 50
$/bbl; 4 in the illustrative Midland deck.
gas_pricenumberOptional≥ 0, ≤ 50
$/mcf; 3.5 in the illustrative Midland deck.
gas_differentialnumberOptional≥ -10, ≤ 10
$/mcf; 1 in the illustrative Midland deck.
ngl_pricenumberOptional≥ 0, ≤ 200
$/bbl; 26 in the illustrative Midland deck.
ngl_yield_bbl_per_mmcfnumberOptional≥ 0, ≤ 300
bbl/MMcf; 130 in the illustrative Midland deck.
shrinknumberOptional≥ 0, ≤ 1
fraction; 0.8 in the illustrative Midland deck.
opex_oilnumberOptional≥ 0, ≤ 100
$/bbl; 5.5 in the illustrative Midland deck.
opex_gasnumberOptional≥ 0, ≤ 20
$/mcf; 0.5 in the illustrative Midland deck.
opex_waternumberOptional≥ 0, ≤ 20
$/bbl; 0.6 in the illustrative Midland deck.
royaltynumberOptional≥ 0, ≤ 0.5
fraction; 0.25 in the illustrative Midland deck.
severance_oilnumberOptional≥ 0, ≤ 0.5
fraction; 0.046 in the illustrative Midland deck.
Show all 20 fields
severance_gasnumberOptional≥ 0, ≤ 0.5
fraction; 0.075 in the illustrative Midland deck.
ad_valoremnumberOptional≥ 0, ≤ 0.2
fraction; 0.025 in the illustrative Midland deck.
capex_per_wellnumberOptional≥ 0, ≤ 50000000
$; 2500000 in the illustrative Midland deck.
capex_drilling_per_ftnumberOptional≥ 0, ≤ 2000
$/ft; 150 in the illustrative Midland deck.
capex_stimulation_per_ftnumberOptional≥ 0, ≤ 2000
$/ft; 125 in the illustrative Midland deck.
capex_proppant_per_lbnumberOptional≥ 0, ≤ 2
$/lb; 0.08 in the illustrative Midland deck.
capex_fluid_per_bblnumberOptional≥ 0, ≤ 50
$/bbl; 3 in the illustrative Midland deck.
discount_ratenumberOptional≥ 0, ≤ 1
fraction per year; 0.25 in the illustrative Midland deck.
conventionsstringOptionalDefault
"prototype"With include value (a 400 without it): how NPV and payback are counted, as POST /economics takes it.
"prototype""fe"
Responses
200 OK
Both sides' echoes, totals, distribution and warnings, with groups, curves, pairs, per-well rows, changed inputs and value when asked.
aobjectRequiredSide a's echo: a plan side's, or a forecast source side's.
ShowHide 2 variants
One of
ComparisonSideEcho object
What one side is and what made it.
kindstringRequiredWhat the side is: plan. A forecast source side's echo is a SourceSideEcho, whose kind is source.
"plan""source"planobjectRequiredThe plan.
ShowHide 2 child fields
idstringRequiredFormat
uuidPlan id.
namestring or nullRequiredPlan name.
scenariostring or nullRequiredThe scenario compared; null for a plan without scenarios.
designobjectRequiredThe design compared.
ShowHide 2 child fields
indexintegerRequired≥ 0
The design, as its index in
designs.namestringRequiredThe design's name.
model_setstringRequiredThe model set that ran the plan: a stored plan's record names it; a plan kept in this server's memory is on the set the request reached.
releasestringRequiredThe app version that ran the plan, as GET /health
app_version: a stored plan's record names it; a plan kept in memory ran on this server's; unknown when the server has no VERSION.run_atstringRequiredFormat
date-timeWhen the plan was created, UTC.
declineobject or nullRequiredThe EUR settings the plan was fit with, as GET /plans/{id}
decline(per_well when one of the side's wells has its own); null without EUR.ShowHide 8 child fields
eur_yearsintegerRequired≥ 10, ≤ 50
Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.
terminal_declinenumberRequired≥ 0.01, ≤ 0.2
Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.
b_minnumberRequired≥ 0, ≤ 2.5
Lowest hyperbolic b the fit may use; below b_max.
b_maxnumberRequired≥ 0, ≤ 2.5
Highest hyperbolic b the fit may use; above b_min.
oilobjectOptionalWith per-stream settings, the settings oil was fit with.
ShowHide 3 child fields
terminal_declinenumberRequired≥ 0.01, ≤ 0.2
Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.
b_minnumberRequired≥ 0, ≤ 2.5
Lowest hyperbolic b the fit may use; below b_max.
b_maxnumberRequired≥ 0, ≤ 2.5
Highest hyperbolic b the fit may use; above b_min.
gasobjectOptionalWith per-stream settings, the settings gas was fit with.
Same fields as StreamDecline.
waterobjectOptionalOnly with eur_water: true: the settings water was fit with. Its presence is the echo of the flag.
Same fields as StreamDecline.
per_wellbooleanOptionalOnly when a well has its own settings: these are the request's or plan's, not every well's;
inputs.resolved.declinegives each well's.true
bandsobject or nullRequiredThe plan's bands, as GET /plans/{id}
bands; null when it was made without them.ShowHide 3 child fields
percentiles[integer, integer]RequiredThe bands' percentiles: 10 (low) and 90 (high).
methodstringRequiredHow the bands are made: Novi's predrill bands (split conformal, safe variant).
eurbooleanRequiredWhether each oil and gas band, and water's with eur_water, has its EUR (band_eur).
wellsintegerRequired≥ 0
The side's wells: the scenario's, else the plan's.
wells_with_forecastintegerRequired≥ 0
Of them, wells with a forecast under the design, as the matching GET /plans/{id}
totalsrow counts them.unplacedobjectRequiredWells the plan couldn't place.
ShowHide 2 child fields
countintegerRequired≥ 0
The side's wells that couldn't be placed (per_well_errors).
messagestring or nullRequiredThe first one's reason; null when none.
SourceSideEcho object
What a forecast source side is and how its numbers were made.
kindstringRequiredA forecast source side.
"source"sourceobjectRequiredThe forecast source.
ShowHide 2 child fields
idstringRequiredFormat
uuidForecast source id.
namestringRequiredIts name.
formatstringRequiredThe file's format, as GET /forecast-sources/{id}
format.fileobjectRequiredThe file the source was read from.
ShowHide 3 child fields
namestring or nullRequiredThe file's name; null when none was sent.
bytesintegerRequired≥ 0
Its size.
read_atstringRequiredFormat
date-timeWhen it was read and saved, UTC.
conventionsobjectRequiredThe profile's conventions, as GET /conventions?include=decline_profiles lists them.
ShowHide 4 child fields
profilestringRequiredThe decline profile its curves ran under.
"valnav""mosaic""combocurve""novi""aries"declinesarray of stringsRequiredThe decline bases the profile reads.
"nominal""secant""tangent"year_daysnumberRequiredDays in the profile's year.
monthsstringRequiredcalendar, or 30-day months from ip day 0.
"calendar""30-day"
unitsstringRequiredThe units the file was in; every number here is converted to bbl, mcf and BOE.
"imperial""metric"gas_basisstringRequiredraw or sales gas, as the source states it; Novi forecasts raw gas.
"raw""sales"reserves_categorystringRequiredThe reserves category compared.
wellsintegerRequired≥ 0
The source's wells under the category.
wells_with_forecastintegerRequired≥ 0
Of them, wells with a stream Novi's Arps decline calculation could run.
curvesintegerRequired≥ 0
The source's curves under the category.
bobjectRequiredSide b's echo: a plan side's, or a forecast source side's.
ShowHide 2 variants
One of
ComparisonSideEcho object
What one side is and what made it.
kindstringRequiredWhat the side is: plan. A forecast source side's echo is a SourceSideEcho, whose kind is source.
"plan""source"planobjectRequiredThe plan.
ShowHide 2 child fields
idstringRequiredFormat
uuidPlan id.
namestring or nullRequiredPlan name.
scenariostring or nullRequiredThe scenario compared; null for a plan without scenarios.
designobjectRequiredThe design compared.
ShowHide 2 child fields
indexintegerRequired≥ 0
The design, as its index in
designs.namestringRequiredThe design's name.
model_setstringRequiredThe model set that ran the plan: a stored plan's record names it; a plan kept in this server's memory is on the set the request reached.
releasestringRequiredThe app version that ran the plan, as GET /health
app_version: a stored plan's record names it; a plan kept in memory ran on this server's; unknown when the server has no VERSION.run_atstringRequiredFormat
date-timeWhen the plan was created, UTC.
declineobject or nullRequiredThe EUR settings the plan was fit with, as GET /plans/{id}
decline(per_well when one of the side's wells has its own); null without EUR.Same fields as Decline.
bandsobject or nullRequiredThe plan's bands, as GET /plans/{id}
bands; null when it was made without them.Same fields as BandsEcho.
wellsintegerRequired≥ 0
The side's wells: the scenario's, else the plan's.
wells_with_forecastintegerRequired≥ 0
Of them, wells with a forecast under the design, as the matching GET /plans/{id}
totalsrow counts them.unplacedobjectRequiredWells the plan couldn't place.
ShowHide 2 child fields
countintegerRequired≥ 0
The side's wells that couldn't be placed (per_well_errors).
messagestring or nullRequiredThe first one's reason; null when none.
SourceSideEcho object
What a forecast source side is and how its numbers were made.
kindstringRequiredA forecast source side.
"source"sourceobjectRequiredThe forecast source.
ShowHide 2 child fields
idstringRequiredFormat
uuidForecast source id.
namestringRequiredIts name.
formatstringRequiredThe file's format, as GET /forecast-sources/{id}
format.fileobjectRequiredThe file the source was read from.
ShowHide 3 child fields
namestring or nullRequiredThe file's name; null when none was sent.
bytesintegerRequired≥ 0
Its size.
read_atstringRequiredFormat
date-timeWhen it was read and saved, UTC.
conventionsobjectRequiredThe profile's conventions, as GET /conventions?include=decline_profiles lists them.
ShowHide 4 child fields
profilestringRequiredThe decline profile its curves ran under.
"valnav""mosaic""combocurve""novi""aries"declinesarray of stringsRequiredThe decline bases the profile reads.
"nominal""secant""tangent"year_daysnumberRequiredDays in the profile's year.
monthsstringRequiredcalendar, or 30-day months from ip day 0.
"calendar""30-day"
unitsstringRequiredThe units the file was in; every number here is converted to bbl, mcf and BOE.
"imperial""metric"gas_basisstringRequiredraw or sales gas, as the source states it; Novi forecasts raw gas.
"raw""sales"reserves_categorystringRequiredThe reserves category compared.
wellsintegerRequired≥ 0
The source's wells under the category.
wells_with_forecastintegerRequired≥ 0
Of them, wells with a stream Novi's Arps decline calculation could run.
curvesintegerRequired≥ 0
The source's curves under the category.
totalsarray of objectsRequiredEUR rows when both sides have EUR, then with horizon the cumulative rows at its day (
horizon_yearsset), then cumulative rows at ip_day for a cum_ metric. A forecast source side's EUR runs each curve to its own limit or end date.ShowHide 10 child fields in each item
metricstringRequiredWhat the row totals.
- eur_<stream>: EUR summed over the side's wells with that EUR (BOE over those with both oil and gas).
- cum_<stream>: the summed forecast's cumulative at ip_day (BOE: the
forecast.boetotal GET /plans/{id}?boe=true serves, over the wells with both oil and gas forecasts); on a horizon row (horizon_yearsset), at that horizon's day (BOE over those with both).
"eur_oil""eur_gas""eur_water""eur_boe""cum_oil""cum_gas""cum_boe"unitstringRequiredThe unit of a, b and delta: bbl (oil, water), mcf (gas) or BOE.
"bbl""mcf""BOE"ip_dayinteger or nullRequiredFor a cum_ row, the ip_day; null for an EUR row.
anumber or nullRequiredSide a's total; null when no well has it.
bnumber or nullRequiredSide b's total; null when no well has it.
deltanumber or nullRequiredb − a, rounded to 0.1; null when either is null.
delta_pctnumber or nullRequired(b − a) / a × 100, relative to side a, rounded to 0.01; null when a is 0 or either is null.
a_wellsintegerRequired≥ 0
Side a's wells the total covers.
b_wellsintegerRequired≥ 0
Side b's wells the total covers.
horizon_yearsintegerOptional≥ 1
On a horizon row only: the years asked; ip_day is that horizon's day.
distributionobjectRequiredEach side's distribution of the metric over its wells, and how it moved.
ShowHide 8 child fields
metricstringRequiredThe metric measured.
"eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"unitstringRequiredThe unit of every value: bbl (oil), mcf (gas) or BOE.
"bbl""mcf""BOE"ip_dayinteger or nullRequiredFor a cum_ metric, the ip_day measured; null for an eur_ metric.
aobjectRequiredOne side's distribution of the metric over its wells, as GET /plans/{id}/stats gives it, in distribution.unit.
ShowHide 8 child fields
wellsintegerRequired≥ 0
Wells with a value; every figure describes them.
missingintegerRequired≥ 0
Wells without one: no forecast, a failed EUR fit, or BOE without both oil and gas.
minnumber or nullRequiredSmallest value; null when no well has one.
maxnumber or nullRequiredLargest value; null when no well has one.
meannumber or nullRequiredMean value per well; null when no well has one.
quantilesobjectRequiredq10, q50 and q90 of the wells' values (linear interpolation between the closest ranks), not P-level bands; each null when no well has a value.
namestringOptionalIn a pad group, this side's name for the pad when its plan gives one in
pads[].name; absent otherwise. The sides are paired bykeyand may name it differently.othersintegerOptional≥ 1
On a group's Other row only: how many of the side's groups it sums.
bobjectRequiredOne side's distribution of the metric over its wells, as GET /plans/{id}/stats gives it, in distribution.unit.
Same fields as ComparisonSpread.
deltaobjectRequiredb − a (rounded to 0.1), or (b − a) / a × 100 relative to side a (rounded to 0.01) as delta_pct.
ShowHide 2 child fields
meannumber or nullRequiredOf the mean per well; null when either side has none.
q50number or nullRequiredOf the median well; null when either side has none.
delta_pctobjectRequiredb − a (rounded to 0.1), or (b − a) / a × 100 relative to side a (rounded to 0.01) as delta_pct.
Same fields as ComparisonDelta.
normalize_lateral_ftnumberOptionalWith normalize_lateral_ft: the lateral every value was scaled to, ft.
warningsarray of objectsRequiredReasons a difference may not come from the plans, in a fixed order; empty when there are none.
ShowHide 2 child fields in each item
codestringRequiredStable code; more may come.
- Any sides: different_model_sets, models_changed, different_releases, different_eur_settings, side_without_eur, wells_without_forecast, side_without_bands, index_pairing, duplicate_names, no_band_position.
- With a forecast source side: gas_basis_differs, conventions_differ, horizons_differ, source_unpaired, and with include value, value_wells_differ.
messagestringRequiredOne sentence to show beside the numbers.
group_bystringOptionalWith group_by: what groups is by.
"design""formation""scenario""pad"groupsarray of objectsOptionalWith group_by: one row per key on either side, in GET /plans/{id}/stats order (scenarios: side a's plan's order, then any only side b's plan has); pad keys use side a plan order then new side b keys, null last, with no cap or Other row. For other groupings, at most 50, the rest in one Other row.
ShowHide 5 child fields in each item
keystring or integer or nullRequiredThe design index, the formation (null for wells without one), the scenario, the pad key (null for wells without one), or Other on the summed row. Pads never fold into Other.
aobject or nullRequiredSide a's wells in the group; null when it has none.
Same fields as ComparisonSpread.
bobject or nullRequiredSide b's wells in the group; null when it has none.
Same fields as ComparisonSpread.
deltaobject or nullRequiredb − a; null when a side has no wells in the group.
Same fields as ComparisonDelta.
delta_pctobject or nullRequiredRelative to side a; null when a side has no wells in the group.
Same fields as ComparisonDelta.
curvesobjectOptionalEach side's summed curve for the metric's stream, with include curves.
ShowHide 7 child fields
axisstringRequiredCurves run by days since TIL (ip_days), not calendar dates.
"ip_days"streamstringRequiredThe metric's stream.
"oil""gas""boe"unitstringRequiredThe cumulative's unit.
"bbl""mcf""BOE"rate_unitstringRequiredThe rate's unit: the volume per day.
"bbl/d""mcf/d""BOE/d"aobject or nullRequiredSide a's; null when none of its wells has the stream (BOE: both oil and gas).
ShowHide 4 child fields
ip_daysarray of integersRequiredItems ≥ 1
The forecast's days.
cumarray of numbersRequiredThe side's summed cumulative, as GET /plans/{id}
totalsforecast(BOE: itsforecast.boewith boe=true, over the wells with both oil and gas forecasts).ratearray of numbersRequiredEach step's rate: the cumulative's rise from the day before (from 0 on day 0) over the days between.
bandsobjectOptionalWith include bands, where the side's plan was made with bands and every well has them; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.
ShowHide 2 child fields
p10array of numbersRequiredThe summed P10 cumulative (Novi's P10 is the low curve).
p90array of numbersRequiredThe summed P90 cumulative.
bobject or nullRequiredSide b's; null when none of its wells has the stream (BOE: both oil and gas).
Same fields as ComparisonCurve.
calendarobjectOptionalWith align calendar: each side's summed curve by calendar month.
ShowHide 2 child fields
aobject or nullRequiredSide a's; null when none of its wells has the stream (BOE: both oil and gas).
ShowHide 4 child fields
datesarray of stringsRequiredEach month start from the side's first TIL month, as GET /plans/{id} totals.by_date.dates.
cumarray of numbersRequiredThe side's cumulative, as totals.by_date; BOE over the wells with both oil and gas, as GET /plans/{id}?boe=true totals count them (each well's oil plus gas / 6, summed, to 0.1).
ratearray of numbersRequiredEach month's rate: the cumulative's rise over the calendar days between month starts; null for the first.
bandsobjectOptionalWith include bands, where every well of the side has bands; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.
ShowHide 2 child fields
p10array of numbersRequiredThe summed P10 (Novi's P10 is the low curve).
p90array of numbersRequiredThe summed P90.
bobject or nullRequiredSide b's; null when none of its wells has the stream (BOE: both oil and gas).
Same fields as ComparisonDateCurve.
pairsobjectOptionalWith pair, include wells or include inputs: how the wells paired.
ShowHide 5 child fields
bystringRequiredThe method that paired them: what pair.by asked, or for auto, name or location.
"name""location""index""map""uwi""saved"pairedintegerRequired≥ 0
Pairs.
a_onlyarray of integer or stringRequiredSide a's wells left unpaired, ascending; a forecast source side's in its file order.
b_onlyarray of integer or stringRequiredSide b's wells left unpaired, ascending; a forecast source side's in its file order.
tolerance_ftnumberOptionalBy location only: the tolerance used, ft.
wellsobjectOptionalWith include wells.
ShowHide 3 child fields
summaryobjectRequiredOver every pair, so the same on every page.
ShowHide 6 child fields
pairedintegerRequired≥ 0
Pairs.
metricstringRequiredThe metric measured.
"eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"unitstringRequiredThe unit of a, b and delta: bbl, mcf or BOE.
"bbl""mcf""BOE"delta_pctobjectRequiredEach pair's percent change, relative to side a.
ShowHide 5 child fields
q10number or nullRequiredOf the pairs' delta_pct (linear between closest ranks), to 0.01; quantiles of pairs, not P-levels.
q50number or nullRequiredThe median pair's.
q90number or nullRequiredOf the pairs' delta_pct.
valuesarray of numbersOptionalUnder 20 pairs: every delta_pct, ascending.
histogramobjectOptionalAt 20 pairs or more.
ShowHide 2 child fields
edgesarray of numbersRequiredEqual-width bins from the smallest to the largest delta_pct; ceil(log2 n) + 1 bins (Sturges, n the pairs with a delta_pct), one when all are equal, none when no pair has one.
countsarray of integersRequiredItems ≥ 0
They add up to the pairs with a delta_pct; the last bin is closed.
left_outintegerRequired≥ 0
Pairs with no delta_pct: side a's value 0, or either value missing.
bandobjectOptionalWith band_eur on side a and an eur_ metric: the four add up to paired.
ShowHide 4 child fields
below_p10integerRequired≥ 0
Pairs whose b is below side a's P10.
p10_p90integerRequired≥ 0
Inside, edges included.
above_p90integerRequired≥ 0
Above side a's P90.
noneintegerRequired≥ 0
Without a position: b or the band missing.
rowsarray of objectsRequiredThis page of the pairs, in wells.sort order.
ShowHide 11 child fields in each item
labelstringRequiredSide a's well name, else Plan well N; a forecast source side a's Well ID.
anumber or nullRequiredSide a's value of the metric, as distribution measures it, to 0.1; null without one.
bnumber or nullRequiredSide b's value, likewise.
deltanumber or nullRequiredb − a, rounded to 0.1; null when either is null.
delta_pctnumber or nullRequired(b − a) / a × 100, relative to side a, rounded to 0.01; null when a is 0 or either is null.
a_indexintegerOptional≥ 0
Side a's plan well index; a forecast source side a has a_well_id instead.
b_indexintegerOptional≥ 0
Side b's plan well index; a forecast source side b has b_well_id instead.
a_well_idstringOptionalSide a's Well ID when side a is a forecast source.
b_well_idstringOptionalSide b's Well ID when side b is a forecast source.
b_labelstringOptionalWhen side b is a plan: its well's name, else Plan well N, as label names side a's; a forecast source side b has b_well_id instead.
band_positionstring or nullOptionalWith band_eur on side a and an eur_ metric: where b falls in side a's P10 to P90 EUR (below_p10, p10_p90 with the edges inside, above_p90); null when b or the band is missing.
"below_p10""p10_p90""above_p90"
next_cursorstring or nullRequiredSend as wells.cursor for the next page; null on the last.
inputsobjectOptionalWith include inputs.
ShowHide 1 child field
changedarray of objectsRequiredOnly inputs that differ on at least one pair, in a fixed order; empty when none do.
ShowHide 4 child fields in each item
fieldstringRequiredThe input: formation, tvd_ft (as landed), lateral_length_ft, fluid_bbl_per_ft, proppant_lb_per_ft (as run under each side's design), til_date, or with EUR on both sides decline.eur_years and decline.<stream>.terminal_decline, b_min or b_max.
unitstring or nullRequiredThe unit of typical_change: ft, bbl/ft, lb/ft, days, years or fraction per year; null for formation and the b exponents.
wellsintegerRequired≥ 1
Pairs where it differs, at the precision it is shown to.
typical_changenumber or object or nullRequirednull when no differing pair has both values.
ShowHide 2 variants
Any of
number number
b − a: the median among the pairs that differ with both values.
For formation: the most common change object
For formation: the most common change.
fromstring or nullRequiredSide a's.
tostring or nullRequiredSide b's.
valueobjectOptionalWith include value: each side priced as one POST /economics scenario under one deck and conventions, and the difference.
ShowHide 6 child fields
labelstringRequiredWhat to show beside the numbers: Simulated half-cycle economics, deck <name>.
deckobjectRequiredThe effective deck.
ShowHide 6 child fields
deck_idstringRequiredThe deck's id.
versionintegerRequired≥ 1
Its version.
namestringRequiredIts display name, as GET /economics/decks lists it; name results by it.
overridesarray of stringsRequiredThe fields this request overrode.
"oil_price""oil_differential""gas_price""gas_differential""ngl_price""ngl_yield_bbl_per_mmcf""shrink""opex_oil""opex_gas""opex_water""royalty""severance_oil""severance_gas""ad_valorem""capex_per_well""capex_drilling_per_ft""capex_stimulation_per_ft""capex_proppant_per_lb""capex_fluid_per_bbl""discount_rate"discount_ratenumberRequiredThe effective annual discount rate used for npv.
valuesobjectRequiredThe values priced with.
ShowHide 20 child fields
oil_pricenumberRequired$/bbl
oil_differentialnumberRequired$/bbl
gas_pricenumberRequired$/mcf
gas_differentialnumberRequired$/mcf
ngl_pricenumberRequired$/bbl
ngl_yield_bbl_per_mmcfnumberRequiredbbl/MMcf
shrinknumberRequiredfraction
opex_oilnumberRequired$/bbl
opex_gasnumberRequired$/mcf
opex_waternumberRequired$/bbl
royaltynumberRequiredfraction
severance_oilnumberRequiredfraction
Show all 20 fields
severance_gasnumberRequiredfraction
ad_valoremnumberRequiredfraction
capex_per_wellnumberRequired$
capex_drilling_per_ftnumberRequired$/ft
capex_stimulation_per_ftnumberRequired$/ft
capex_proppant_per_lbnumberRequired$/lb
capex_fluid_per_bblnumberRequired$/bbl
discount_ratenumberRequiredfraction per year
conventionsstringRequiredThe conventions priced under.
"prototype""fe"aobjectRequiredOne side priced.
ShowHide 6 child fields
economicsobject or nullRequiredThe side's economics, as POST /economics gives a scenario's, or null.
ShowHide 4 child fields
capexnumberRequiredCapex, $, all at month 0.
irr_pctnumber or nullRequiredIRR, % a year, annualized from the monthly rate (capped at 100% a month); null when the flows never return their capex.
payback_monthsnumber or nullRequiredMonths until the running total turns non-negative: interpolated within the month, or whole months under fe; null when it never does.
npvnumberRequiredNPV, $, at the effective deck discount_rate, discounted as conventions says.
reasonstring or nullRequiredWhy economics is null: the first well without a cash flow and why, as POST /economics names it, or that none of a forecast source side's wells paired.
breakevenobject or nullRequiredAs POST /economics include breakeven gives a scenario's: the flat oil and gas prices at which the side's npv is 0, every other deck value and override held; null when economics is null.
ShowHide 3 child fields
oil_pricenumber or nullRequiredWTI, $/bbl: the flat oil price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between oil_price's min and max (GET /economics/deck).
gas_pricenumber or nullRequiredHenry Hub, $/mcf: the flat gas price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between gas_price's min and max.
discount_ratenumberRequiredThe effective annual discount rate npv was taken at, as deck.discount_rate.
wellsintegerRequired≥ 1
The side's wells: a plan side's, or every well of a forecast source side under its reserves category.
pricedintegerRequired≥ 0
Wells with a cash flow.
unpricedarray of objectsRequiredOn a forecast source side, each well that didn't pair with a plan well, in the source's order; empty on a plan side.
ShowHide 2 child fields in each item
well_idstringRequiredThe forecast source's Well ID.
reasonstringRequiredWhy it isn't priced.
bobjectRequiredOne side priced.
Same fields as ComparisonValueSide.
deltaobjectRequiredb − a, rounded half away from 0 to 0.01: swapping the sides negates every value, and a side against itself gives 0.
ShowHide 5 child fields
capexnumber or nullRequiredb − a, $, to 0.01; null when a side has no economics.
npvnumber or nullRequiredb − a, $, to 0.01; null when a side has no economics.
irr_pctnumber or nullRequiredb − a, percentage points, to 0.01; null when a side has no economics or no IRR.
payback_monthsnumber or nullRequiredb − a, months, to 0.01; null when a side has no economics or never pays back.
breakevenobjectRequiredb − a of each breakeven price.
ShowHide 2 child fields
oil_pricenumber or nullRequiredb − a, $/bbl, to 0.01; null when a side has no breakeven oil price.
gas_pricenumber or nullRequiredb − a, $/mcf, to 0.01; null when a side has no breakeven gas price.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | The request conflicts with the state of the plan or resource it names, and |
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean