Get one plan well
A done plan's well in full, shaped like a POST /forecasts well: its summary, spacing neighbors (other plan wells by their DRAWN key and label), spacing features at ip_day 1 and subsurface values.
Get one plan well
/plans/{id}/wells/{index}A done plan's well in full, shaped like a POST /forecasts well: its summary, spacing neighbors (other plan wells by their DRAWN key and label), spacing features at ip_day 1 and subsurface values.
Options
eur_curve adds the curve of each oil and gas EUR, boe=true each forecast's BOE, and include=scored_inputs the inputs each design scored, by feature name.
Caching
The answer carries an ETag; send it as If-None-Match for a 304.
Parameters
Path parameters
idstringRequiredFormat
uuidPlan id from POST /plans.
indexintegerRequired≥ 0
The well's position in the plan, from 0.
Query parameters
eur_curvestringOptionalAdd each oil and gas EUR's curve (and water's with
eur_water),eur.curve, on a plan made witheur: true(400 otherwise): cumulative volumes to the EUR'sdays.It continues the forecast from its last ip_day on the same decline fit:
monthevery 30 days (the export's monthly cumulatives),yearevery 360 days plus the EUR's day. A decline-curve extension, not a model output."month""year"boebooleanOptionalDefault
falsetrueaddsboebesideoil,gasandwaterin every forecast that has streams, computed when read, so older plans have it too. Absent, empty orfalse: noboekey anywhere.BOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.
Its P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in
wells. With eur_curve, BOE's EUR has its curve too. Anything else is a 400.includestringOptionaldecline_baseaddsinputs.resolved.decline.basewhen the well hasresolved.decline, and nothing otherwise; older plans leave it out.scored_inputsaddsscored_inputs, the inputs each design scored, by feature name. Names may be comma-separated or repeated, each once. Unknown or duplicate names are 400."decline_base""scored_inputs""decline_base,scored_inputs""scored_inputs,decline_base"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.
Responses
200 OK
The plan well.
indexintegerRequired≥ 0
Position of the well in the request.
keystringRequiredKey the models use for the well, as DRAWN-<index>; other drawn wells appear among neighbors by this key.
labelstringRequiredDisplay name: Plan well N in a plan, Drawn well N from POST /forecasts, counting from 1.
inputsobjectRequiredThe well as requested, blanks as null. tvd_ft, landing_below_top_ft, landing_fraction and til_date show a layer's value when the well took one.
ShowHide 16 child fields
shl[number, number]RequiredSurface hole location, [lng, lat].
bhl[number, number]RequiredBottom hole (toe) location, [lng, lat]. The lateral runs from heel, else shl, to bhl and must be 100 to 50,000 ft long.
formationstring or nullRequiredTarget formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD.
tvd_ftnumber or nullRequired> 0, < 40000
True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.
landing_below_top_ftnumber or nullRequired> -40000, < 40000
Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's
subsurface_sampling(GET /model-sets).heel[number, number]OptionalThe heel sent; only when the request sent one.
typed_lateralobjectOptionalThe typed_lateral sent; only when the request sent one.
ShowHide 3 child fields
length_ftnumberRequired≥ 0, ≤ 1000000
The typed length, ft.
heel[number, number]RequiredWhere the lateral started when the length was typed: the well's heel, else its shl, [lng, lat].
bhl[number, number]RequiredThe bottom hole the length was typed for, [lng, lat].
landing_fractionnumberOptional≥ 0, ≤ 1
The landing_fraction sent; only when the request sent one.
til_datestringOptionalFormat
dateThe TIL date the well ran with: its own, else its pad's or layout's, else its scenario's, else the request's til_date. Only when the request sent a date for it; otherwise the well was TIL today.
scenariostringOptionalThe well's scenario, only when the request sent scenarios.
fluid_bbl_per_ftnumberOptionalThe well's own fluid sent, bbl/ft; only when the request sent one.
proppant_lb_per_ftnumberOptionalThe well's own proppant sent, lb/ft; only when the request sent one.
Show all 16 fields
stage_length_ftnumberOptionalThe well's own stage_length_ft sent; only when the request sent one and the set's models read it.
clusters_per_stagenumberOptionalThe well's own clusters_per_stage sent; only when the request sent one and the set's models read it.
frac_rate_bbl_per_minnumberOptionalThe well's own frac_rate_bbl_per_min sent; only when the request sent one and the set's models read it.
resolvedobjectOptionalWhat this well was forecast with: its completions once a well, pad, layout or scenario of the request sets one, its TIL date and landing once a pad, scenario or
formationsentry sets one that a well takes (a layout alone doesn't), and then on every well. Read each key as optional: a later release may send some of these and add others.ShowHide 9 child fields
fluid_bbl_per_ftobjectOptionalFluid used, bbl/ft.
ShowHide 2 child fields
valuenumberRequiredThe value the well was forecast with.
layerstringRequiredThe narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's
assumption_set.filledlists those fields.- well: the well.
- pad_formation: its pad's
formationsentry for its formation, or its layout bench. - pad: its
padsentry, or its layout. - scenario_formation: its scenario's
formationsentry for its formation. - scenario: its
scenariosentry. - plan_formation: the design's entry for its formation, or for a landing the request's
formationsentry. - plan: the design, or the request's til_date.
- default: nothing set it.
"well""pad_formation""pad""scenario_formation""scenario""plan_formation""plan""default"
proppant_lb_per_ftobjectOptionalProppant used, lb/ft.
Same fields as ResolvedValue.
stage_length_ftobjectOptionalThe stage_length_ft used, on a model set whose models read it.
Same fields as ResolvedValue.
clusters_per_stageobjectOptionalThe clusters_per_stage used, on a model set whose models read it.
Same fields as ResolvedValue.
frac_rate_bbl_per_minobjectOptionalThe frac_rate_bbl_per_min used, on a model set whose models read it.
Same fields as ResolvedValue.
completions_sourcestringOptionalinput when a request set both, else how the default was found.
til_dateobjectOptionalA TIL date and the layer it came from.
ShowHide 2 child fields
layerstringRequiredThe narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's
assumption_set.filledlists those fields.- well: the well.
- pad_formation: its pad's
formationsentry for its formation, or its layout bench. - pad: its
padsentry, or its layout. - scenario_formation: its scenario's
formationsentry for its formation. - scenario: its
scenariosentry. - plan_formation: the design's entry for its formation, or for a landing the request's
formationsentry. - plan: the design, or the request's til_date.
- default: nothing set it.
"well""pad_formation""pad""scenario_formation""scenario""plan_formation""plan""default"valuestringOptionalFormat
dateThe TIL date the well ran with; left out when no layer set one, and the well ran on the plan's start day, or today in POST /forecasts.
landingobjectOptionalThe landing a layer set, and which: one of the three, or none with layer default, when TVD was estimated.
estimates.tvd_ftis the TVD the well ran at.ShowHide 4 child fields
layerstringRequiredThe narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's
assumption_set.filledlists those fields.- well: the well.
- pad_formation: its pad's
formationsentry for its formation, or its layout bench. - pad: its
padsentry, or its layout. - scenario_formation: its scenario's
formationsentry for its formation. - scenario: its
scenariosentry. - plan_formation: the design's entry for its formation, or for a landing the request's
formationsentry. - plan: the design, or the request's til_date.
- default: nothing set it.
"well""pad_formation""pad""scenario_formation""scenario""plan_formation""plan""default"tvd_ftnumberOptionalThe TVD set, ft.
landing_below_top_ftnumberOptionalThe landing below the formation top set, ft.
landing_fractionnumberOptionalThe fraction of the formation's thickness set.
declineobjectOptionalThe EUR settings this well was fit with, each value with the layer that set it.
On every well once a well, pad, layout or bench, scenario or
formationsentry of the request sets one; a plan with no layer below it has noresolved.decline, and itsdeclineecho's flat fields are the base. A stream's value beats its layer's base, and the narrower layer wins first: a well'sb_maxbeats a plan'soil.b_max.ShowHide 5 child fields
eur_yearsobjectRequiredYears to EUR, every stream's.
Same fields as ResolvedValue.
oilobjectRequiredWhat one stream was fit with, each value with its layer.
ShowHide 3 child fields
terminal_declineobjectRequiredTerminal decline, as a fraction per year.
Same fields as ResolvedValue.
b_minobjectRequiredLowest b.
Same fields as ResolvedValue.
b_maxobjectRequiredHighest b.
Same fields as ResolvedValue.
gasobjectRequiredWhat one stream was fit with, each value with its layer.
Same fields as ResolvedStreamDecline.
waterobjectOptionalOnly with eur_water: true.
Same fields as ResolvedStreamDecline.
baseobjectOptionalOnly with include=decline_base on GET /plans/{id} or GET /plans/{id}/wells/{index}: the flat terminal_decline, b_min and b_max this well ran with, which a stream's value goes over. Left out on older plans.
- Each
layeris the narrowest layer whose flat field set it (planfor the request's flatdecline), elsedefault. A value sent on a stream names its layer only on that stream (oil,gas), so compare them to tell the two apart. - The depletion chain's water extension reads these settings.
- Rebuild a plan's own
declinefrom itsdeclineecho, withoutper_well, not from theplanvalues here: a plan field every well beats isn't here, and the request's flat pair and each stream's are checked on their own.
Same fields as ResolvedStreamDecline.
- Each
lateral_length_ftintegerRequiredThe lateral length the model got, ft, rounded: the well's
typed_laterallength when it applies, else from the heel when the well has one, else shl, to bhl.estimatesobjectRequiredThe TVD the models used, entered or estimated.
ShowHide 2 child fields
tvd_ftnumberRequiredTVD used, ft.
tvd_sourcestringRequiredinput, or how it was estimated.
forecastsarray of objectsRequiredOne forecast per design, in design order.
ShowHide 2 variants in each item
One of
Option 1 object
Forecasts per stream, and the checks of their inputs. A v2 forecast carries the streams its model set serves (GET /model-sets
streams), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Planstreams) carries only those.designintegerRequired≥ 0
The design, as its index in
designs.checksobjectRequiredInputs the model rarely or never saw in training, or why they weren't checked.
Every ip_day's row of this design is checked against the oil model's training statistics (on a set without oil, the first served stream's model: gas, else water); the streams share features. An input is out of range only when it is more than 5% of its training 1st to 99th percentile range outside that range. Neighbors' production (parent depletion near the well) is reported in
contextinstead.ShowHide 2 variants
One of
Checked inputs object
Checked inputs.
availableanyRequiredAlways
trueThe inputs were checked.
model_numstringRequiredModel whose training statistics were used: the oil model, or on a set without oil the first served stream's.
flaggedbooleanRequiredTrue when out_of_range, missing or unknown_formation reports anything; context doesn't set it. When true, show the flag beside any number you quote from this well and design.
out_of_rangearray of objectsRequiredNumeric inputs outside training in any row, one per feature, in the model's feature order: say each is outside the model's training data, with its value and range.
Outside means more than 5% of the training range (99th minus 1st percentile) below the 1st or above the 99th percentile of training. A feature whose two percentiles are equal has no margin. The value a feature takes for no such neighbor (days online -1, distances at the spacing defaults) isn't checked, and neighbors' production features are in
context.ShowHide 5 child fields in each item
featurestringRequiredModel feature, as novi_lateral_length.
valuenumberRequiredThe value farthest outside the training range over the rows, in the feature's unit.
lownumberRequired1st percentile of the feature in training, leaving out the features' no-neighbor value.
highnumberRequired99th percentile of the feature in training, leaving out the features' no-neighbor value.
sidestringRequiredbelow low or above high.
"below""above"
missingarray of stringsRequiredInputs blank in any row, of those blank in under 5% of training rows (inputs often blank in training aren't listed).
unknown_formationstring or nullRequiredThe target formation when the model has no training rows in it, else null.
contextarray of objectsOptionalNeighbors' production features (novi_spacing_sum_prior_, novi_spacing_delgados_p) below the 1st or above the 99th percentile of training in any row, with no margin. They don't set flagged; absent when there are none.
One per feature, in the model's feature order. They measure the parent depletion near the well: how much nearby parents have produced by its TIL, weighted by how close they are. It moves with where the lateral is drawn more than with completions, and a well drawn today near parents that have produced for years often reads above training. Say the well has more (or less) parent depletion nearby than nearly all training wells, not that an input is unusual.
Same fields as InputOutOfRange.
Inputs not checked object
Inputs not checked.
availableanyRequiredAlways
falseThe inputs weren't checked.
reasonstringRequiredWhy, as no training statistics for the model.
oilobjectOptionalOne stream's forecast: cumulative volume at each ip_day, or why it couldn't run.
ShowHide 2 variants
One of
A forecast stream object
A forecast stream.
model_numstringRequiredModel that produced the forecast.
targetstringRequiredModel target column, as novi_oil.
unitstringRequiredVolume unit: bbl for oil and water, mcf for gas.
"bbl""mcf"ip_daysarray of integersRequiredip_days with a forecast, ascending.
valuesarray of numbersRequiredCumulative volumes, one per ip_day.
missingarray of stringsRequiredModel features that were blank for this well and fell back to the model's own handling.
eurobjectOptionalWith eur: true, on oil and gas, and on water with eur_water: true: the EUR, fit on every ip_day of the forecast (before any ip_days filter).
ShowHide 2 variants
One of
An EUR object
An EUR.
valuenumberRequiredCumulative volume at days: the forecast to its last ip_day, then the decline curve (bbl for oil, mcf for gas).
daysintegerRequiredip_day the EUR is at: the last 30-day step within eur_years.
arpsobjectRequiredThe modified Arps curve fitted to the extension, not to the 3-year forecast itself.
ShowHide 4 child fields
q_inumber or nullRequiredInitial rate of the extension fit, per day (0 for a dry well).
dnumber or nullRequiredNominal decline of the extension fit, per day.
bnumber or nullRequiredHyperbolic exponent of the extension fit.
terminal_yearnumber or nullRequiredYear the curve switches to terminal (exponential) decline.
curveobjectOptionalWith eur_curve: the cumulative from the forecast's last ip_day to days.
ShowHide 2 variants
One of
The curve object
The curve.
step_daysintegerRequired30 for month, 360 for year.
30360ip_daysarray of integersRequiredFrom the forecast's last ip_day plus one step to the EUR's days, ascending: every 30 days (month), or every 360 days and the EUR's days last (year).
valuesarray of numbersRequiredCumulative volumes to 0.01, one per ip_day, continuing the forecast's values; the last is the EUR's value to 0.01.
No curve object
No curve.
errorstringRequiredWhy there is no curve: the decline fit returned no extension, the forecast worker failed to fit one again (POST /forecasts), or the extension doesn't end on this EUR at its day on the forecast's month grid.
No EUR object
No EUR.
errorstringRequiredWhy there is no EUR, as the decline fit reports it.
bandsobjectOptionalWith bands: true: the P10 (low) and P90 (high) cumulative curves on these ip_days, or why this stream has none.
ShowHide 2 variants
One of
Option 1 object
Bands: Novi's predrill bands (split conformal, safe variant), the conformal P10 (low) and P90 (high) at each ip_day around this forecast, stabilized from their rates so each stays cumulative. They usually bracket the forecast but aren't guaranteed to.
p10objectRequiredThe low curve (P10 in Novi's convention): the conformal lower bound at each ip_day, stabilized. Usually below the forecast, but not always: it is rebuilt from non-negative rates, so it can sit above the forecast where the forecast's cumulative dips.
ShowHide 2 child fields
valuesarray of numbersRequiredThe band's cumulative volumes, one per ip_day of the stream.
eurobjectOptionalWith band_eur: true, on oil and gas, and on water with eur_water: true: this band's EUR, fit like the forecast's (every ip_day, the same decline settings).
Same fields as Eur.
p90objectRequiredThe high curve (P90 in Novi's convention): the conformal upper bound at each ip_day, stabilized. Usually above the forecast, but not guaranteed to be.
Same fields as Band.
No bands object
No bands.
errorstringRequiredWhy this stream has no bands.
A stream that failed object
A stream that failed.
errorstringRequiredWhy this stream has no forecast.
gasobjectOptionalOne stream's forecast: cumulative volume at each ip_day, or why it couldn't run.
Same fields as StreamForecast.
waterobjectOptionalOne stream's forecast: cumulative volume at each ip_day, or why it couldn't run.
Same fields as StreamForecast.
boeobjectOptionalWith boe: true: the forecast's BOE beside its streams, or why it has none.
BOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.
Its P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in
wells.ShowHide 2 variants
One of
BOE object
BOE.
unitstringRequiredAlways BOE.
"BOE"ip_daysarray of integersRequiredOil's ip_days (with ip_days, only those asked for).
valuesarray of numbersRequiredBOE cumulative volumes, one per ip_day.
wellsintegerOptional≥ 1
On totals only: the wells summed, those whose own BOE is ok (both an oil and a gas forecast on the same ip_days). Oil's and gas's own totals may cover more wells.
eurobjectOptionalOn a well's forecast with eur: true: oil's EUR plus gas's / 6. Totals have none: their BOE EUR is in totals[].eur.boe.
ShowHide 2 variants
One of
A BOE EUR object
A BOE EUR.
valuenumberRequiredOil EUR plus gas EUR / 6, to 0.1.
daysintegerRequiredThe later of oil's and gas's EUR days.
curveobjectOptionalWith eur_curve, when oil's and gas's EURs both have curves: BOE's cumulative curve, or why there is none.
ShowHide 2 variants
One of
The BOE curve object
The BOE curve.
step_daysintegerRequiredThe streams' curve step: 30 for month, 360 for year.
30360ip_daysarray of integersRequiredThe union of oil's and gas's curve ip_days, ascending: each stream's steps and its own EUR day, so the shorter stream's EUR day can fall between two steps.
valuesarray of numbersRequiredOil's cumulative plus gas's / 6 at each ip_day, to 0.01: each stream linear between its curve points from its forecast's last value, and held at its EUR after its last point. The last is at the later EUR day: a stream whose curve ends there gives its last curve value (to 0.01), and one whose curve ended sooner its EUR, so it may differ from
valuein its last digit, asvalueis to 0.1.
No BOE curve object
No BOE curve.
errorstringRequiredWhy there is no BOE curve: oil's or gas's curve failed or is missing, named, oil before gas.
No BOE EUR object
No BOE EUR.
errorstringRequiredWhy there is no BOE EUR: oil's or gas's EUR failed, named, oil before gas.
bandsobjectOptionalWith bands: true: BOE's P10 and P90, or why it has none. On totals, summed over the wells summed when every one has BOE bands.
ShowHide 2 variants
One of
BOE bands object
BOE bands.
p10objectRequiredThe low curve: oil's P10 plus gas's P10 / 6.
ShowHide 2 child fields
valuesarray of numbersRequiredOne per ip_day of the BOE.
eurobjectOptionalWith band_eur: true: this band's oil EUR plus gas EUR / 6.
Same fields as BoeEur.
p90objectRequiredThe high curve: oil's P90 plus gas's P90 / 6.
Same fields as BoeBand.
No BOE bands object
No BOE bands.
errorstringRequiredWhy there are none: oil's or gas's bands failed (named, oil before gas), or on totals some wells summed have none.
No BOE object
No BOE.
errorstringRequiredWhy there is no BOE: a stream failed (named, oil before gas), oil and gas are on different ip_days, or on totals no well has both.
No forecast object
No forecast.
designintegerRequired≥ 0
The design, as its index in
designs.errorstringRequiredWhy the well has no forecast.
spacingobjectRequiredSpacing.
ShowHide 2 child fields
nodeobjectRequiredThe drawn well's spacing node.
ShowHide 4 child fields
azimuthnumber or nullRequiredLateral azimuth, degrees.
heelarray of numbersRequired2 items
Heel [lng, lat]: the surface hole, or estimated from a pad of existing wells within 200 ft.
heel_is_virtualbooleanRequiredHeel estimated rather than drawn.
pad_wellsintegerRequiredExisting wells on the same pad.
neighborsarray of objectsRequiredNeighbors, closest first.
ShowHide 19 child fields in each item
neighborstringRequiredNeighbor wellbore key, or DRAWN-<index> for another drawn well.
positionstringRequiredlateral, stack or stagger.
well_namestring or nullOptionalNeighbor name.
operatorstring or nullOptionalNeighbor operator.
formationstring or nullOptionalNeighbor formation.
first_prodstring or nullOptionalFormat
dateNeighbor first production.
heel_lonnumber or nullOptionalNeighbor heel longitude.
heel_latnumber or nullOptionalNeighbor heel latitude.
bhl_lonnumber or nullOptionalNeighbor bottom hole longitude.
bhl_latnumber or nullOptionalNeighbor bottom hole latitude.
conestring or nullOptionalCone, as leftstaggerbelow.
categorystring or nullOptionalparent or nonparent.
Show all 19 fields
signedxynumber or nullOptionalHorizontal offset, ft (+ right looking heel to toe).
signedtvdnumber or nullOptionalVertical offset, ft (+ deeper).
minxynumber or nullOptionalMinimum horizontal distance, ft.
mintvdnumber or nullOptionalMinimum vertical distance, ft.
mintangentnumber or nullOptionalMinimum 3D distance, ft.
overlapnumber or nullOptionalFraction of the lateral the neighbor overlaps.
edge_datestring or nullOptionalFormat
dateDate the edge applies from.
featuresobject or nullRequiredSpacing features at ip_day 1.
subsurfaceobjectRequiredSubsurface values at the well (empty without a formation).
lateral_length_sourcestringOptionalOnly on a well sent a
typed_lateral: typed when the well uses its length_ft, measured when it uses the length between the ends instead."typed""measured"namestringOptionalThe name the request gave the well, trimmed; only when it gave one.
labeldoesn't change.explanationsarray of objectsOptionalWith explain: true, one per design, in design order.
ShowHide 2 variants in each item
One of
Explanations per stream object
Explanations per stream. Only the streams the model set serves (GET /model-sets
streams): a set serving gas alone answers gas alone.designintegerRequired≥ 0
The design, as its index in
designs.oilobjectOptionalOne stream model's explanation of the forecast, or why it couldn't run.
ShowHide 2 variants
One of
An explained stream object
An explained stream.
model_numstringRequiredModel explained.
unitstringRequiredVolume unit of the contributions.
"bbl""mcf"shaparray of objectsRequiredSHAP per ip_day, ascending.
ShowHide 6 child fields in each item
ip_dayintegerRequiredDays since first production.
expected_valuenumber or nullRequiredThe model's average forecast at this ip_day (its baseline).
valuesobjectRequiredContribution of each feature (non-zero only), in the stream's unit; expected_value plus these approximates the forecast, exactly only where the model's SHAP is additive (
residualsays how far it is). With explain_top / top, the largest ones and(other), the sum of the rest.inputsobjectOptionalWith explain_inputs (POST /forecasts) or inputs=true (plan well): the value of each feature
valueslists (not(other)) as the model read it in this ip_day's model row. Numbers are unrounded, in the feature's unit (GET /models/{model_num} lists each input with its training range); categories such as novi_formation are strings; null where the row had none.forecastnumber or nullOptionalWith residual=true (plan well) or explain_residual (POST /forecasts): the forecast served at this ip_day for this design, in the stream's unit, the same number GET /plans/{id}/wells/{index} serves there (on POST /forecasts, the well's
forecasts[d]value beforeip_dayscuts it); null where none is served.residualnumber or nullOptionalWith residual=true or explain_residual: forecast − expected_value − the sum of values (of the uncut row, whatever top keeps), unrounded: the part of the forecast the SHAP values don't attribute. Null when forecast or expected_value is null.
contributing_wellsarray of objectsRequiredTraining wells sharing the forecast's tree leaves, heaviest first (top 25, or explain_top / top). On a causal model set (GET /model-sets?include=model_type), they are the training wells sharing the leaves its baseline (associative) model's prediction used, weighted before the completion effect is applied. Empty when the model's fit has no tree weights: SHAP still explains the forecast.
ShowHide 10 child fields in each item
keystringRequiredWellbore key; GET /wells/{key} has its details.
weightnumberRequired≥ 0, ≤ 1
Share of the forecast's tree weight.
well_namestring or nullRequiredWell name.
operatorstring or nullRequiredOperator.
formationstring or nullRequiredFormation.
first_prodstring or nullRequiredFormat
dateFirst production date.
heel_lonnumber or nullRequiredHeel longitude.
heel_latnumber or nullRequiredHeel latitude.
bhl_lonnumber or nullRequiredBottom hole longitude.
bhl_latnumber or nullRequiredBottom hole latitude.
other_weightnumberRequired≥ 0, ≤ 1
Weight of every other training well (1 minus the listed weights); 1 when the fit has no tree weights and
contributing_wellsis empty.weighted_wellsinteger or nullOptional≥ 0
With weight_counts or explain_weight_counts: training wells with nonzero weight, of which
contributing_wellslists the heaviest; null when the fit has no tree weights or the model worker sent no counts for it, 0 when every weight is 0.effective_wellsnumber or nullOptional≥ 1
With weight_counts or explain_weight_counts: the effective number of training wells the weight rests on, 1/Σw² over every training well's weight (weights sum to 1), to 0.001. It equals
weighted_wellswhen the weight is spread evenly and nears 1 when one well carries it; null when the fit has no tree weights, the model worker sent no counts for it or every weight is 0.weights_errorstringOptionalWith weight_counts or explain_weight_counts, when the fit has no tree weights: why, so
weighted_wellsandeffective_wellsare null; also when the model worker sent no counts for the fit.comparisonsarray of objectsOptionalWith compare or explain_compare: one per reference, in the order asked.
ShowHide 2 variants in each item
One of
A comparison object
A comparison.
referencestringRequiredThe reference.
"formation""dataset""analogs"formationstring or nullRequiredWith formation, the formation the reference covers; null for dataset; with analogs, this well's.
labelstringRequiredThe reference in words, as Typical Wolfcamp A well.
sourcestringRequiredThe population the reference's mean SHAP is over, in words, as "mean SHAP over the WOLFCAMP A wells of the existing wells the model explained (…), per ip_day".
rowsarray of objectsRequiredOne per SHAP row (one with ip_day).
ShowHide 5 child fields in each item
ip_dayintegerRequiredDays since first production.
wellsintegerRequired≥ 0
Reference wells at this ip_day.
valuenumber or nullRequiredThe reference wells' average model forecast here as SHAP gives it: their mean expected_value plus their mean contributions, in the stream's unit; with no stored mean expected_value, this well's expected_value plus their mean contributions (start_from says which). Null with fewer than 5 wells.
valuesobjectRequiredThis well's contribution minus the reference's mean contribution, by feature, in the stream's unit. value plus these is this well's expected_value plus its SHAP values, which approximates its forecast.
(baseline), when it rounds to non-zero: this well's expected_value less the reference wells' mean, which SHAP assigns to no input. In models that scale by lateral length it is mostly this well's lateral against theirs.- Add the SHAP row's residual for the forecast.
- With top, the largest feature differences and
(other), plus(baseline), which top never counts or folds.
start_fromstringOptionalWhere value starts: reference, the reference wells' stored mean expected_value; well, this well's own expected_value, where no mean is stored (values then has no (baseline)). Only on a row with a value.
"reference""well"
keysarray of stringsOptionalWith analogs only: the wells averaged, nearest first, the first 15 (or fewer) of the stream's analogs list.
No comparison object
No comparison.
referencestringRequiredThe reference.
"formation""dataset""analogs"errorstringRequiredWhy there is no baseline, as the model has no baseline for DEAN.
analog_spreadobjectOptionalWith spread or explain_spread: what the contributing wells actually produced, scaled to this lateral. For a fit without tree weights,
{error}with the model's reason.ShowHide 2 variants
One of
A spread object
A spread.
basisstringRequiredWhat the spread is of, in words.
lateral_length_ftintegerRequiredThis well's lateral, ft: every contributing well is scaled to it.
wells_consideredintegerRequired≥ 0
Contributing wells taken (the 50 heaviest).
min_wellsintegerRequired≥ 1
Fewest wells for quantiles.
rowsarray of objectsRequiredOne per ip_day of the SHAP rows.
ShowHide 7 child fields in each item
ip_dayintegerRequiredDays since first production.
wellsintegerRequired≥ 0
Contributing wells whose production reached this ip_day.
q10number or nullRequired10th percentile of their scaled cumulatives, the low end; null with fewer than min_wells.
q50number or nullRequiredMedian; null with fewer than min_wells.
q90number or nullRequired90th percentile, the high end; null with fewer than min_wells.
forecaststring or nullRequiredWhere the served forecast at this ip_day falls against q10 to q90; null without quantiles or a served forecast.
"below""within""above"driverobject or nullOptionalWith driver=true or explain_driver: the input that moves the forecast furthest the way
forecastpoints; null when it is within or null, or when no input moves it that way.ShowHide 3 child fields
featurestringRequiredThe model input, as novi_spacing_parent_daysonline; GET /models/{model_num} lists them.
valuenumberRequiredIts contribution in the stream's unit, rounded to 0.001: negative when the flag is below, positive when above. Against the formation's typical well with reference formation, else the raw SHAP value.
referencestringRequiredWhat the contribution is measured against: formation, the typical well of this well's formation at this ip_day (its mean SHAP over at least 5 wells, as compare=formation); model, the model's average well (the raw SHAP value).
"formation""model"
No spread object
No spread.
errorstringRequiredWhy there is no spread.
analogsobjectOptionalWith analogs or explain_analogs: the model's analog wells for this forecast and, when their measured coverage passes the gate, their spread; for fits with or without tree weights.
ShowHide 2 variants
One of
The model analogs object
The model analogs.
methodstringRequiredHow they were chosen: two stages, hard filters then the distance over standard scores weighted by the model's mean |SHAP|, unless
analog_weightsis present, then by those weights for the inputs it names."shap_weighted"notestringRequiredAlways "Analog spread, not the model's uncertainty".
basisstringRequiredWho they are, in words: the filters, how many wells passed them and the ip_day of the distance.
formationstringRequiredThe formation they share with this well.
childboolean or nullRequiredThis well's parent (false) or child (true) status, which they share; null when its spacing features don't say, and then both count.
lateral_band_pctinteger or nullRequiredHow far their laterals may be from this well's, %: 25, widened to 50 then 100 until 5 wells pass; null when fewer pass even at 100, and then any lateral counts.
2550100candidatesintegerRequired≥ 0
Training wells that passed the filters; the nearest 50 are listed.
weightsarray of objectsRequiredEvery numeric model input, heaviest first.
ShowHide 3 child fields in each item
featurestringRequiredA numeric model input.
weightnumberRequired≥ 0, ≤ 1
Its share of the distance: the model's mean |SHAP| for it at its last ip_day, over the wells the build explained, or with analog_weights the share the distance used; they sum to 1. Formation is a filter, not a weight.
model_weightnumberOptional≥ 0, ≤ 1
With analog_weights: the model's own weight for it, as
weightis without them.
wellsarray of objectsRequiredup to 50 items
Up to 50, nearest first (ties by key);
topdoesn't cut them.ShowHide 22 child fields in each item
keystringRequiredWellbore key; GET /wells/{key} has its details.
distancenumberRequired≥ 0
Its distance from this forecast in the model's weighted standard scores; 0 is the same inputs.
well_namestring or nullRequiredWell name.
operatorstring or nullRequiredOperator.
formationstring or nullRequiredFormation.
first_prodstring or nullRequiredFormat
dateFirst production date.
lateral_lengthnumber or nullRequiredLateral length, ft.
heel_lonnumber or nullRequiredHeel longitude.
heel_latnumber or nullRequiredHeel latitude.
bhl_lonnumber or nullRequiredBottom hole longitude.
bhl_latnumber or nullRequiredBottom hole latitude.
cum_oil_360number or nullOptionalWith analogs_detail: its actual cumulative oil at ip_day 360, bbl, unscaled; null when it hasn't produced that long.
Show all 22 fields
cum_oil_720number or nullOptionalWith analogs_detail: its actual cumulative oil at ip_day 720, bbl, unscaled; null when it hasn't produced that long.
cum_oil_1080number or nullOptionalWith analogs_detail: its actual cumulative oil at ip_day 1080, bbl, unscaled; null when it hasn't produced that long.
cum_gas_360number or nullOptionalWith analogs_detail: its actual cumulative gas at ip_day 360, mcf, unscaled; null when it hasn't produced that long.
cum_gas_720number or nullOptionalWith analogs_detail: its actual cumulative gas at ip_day 720, mcf, unscaled; null when it hasn't produced that long.
cum_gas_1080number or nullOptionalWith analogs_detail: its actual cumulative gas at ip_day 1080, mcf, unscaled; null when it hasn't produced that long.
cum_oil_lifenumber or nullOptionalWith analogs_detail: its cumulative oil to date, bbl.
cum_gas_lifenumber or nullOptionalWith analogs_detail: its cumulative gas to date, mcf.
eur_oilnumber or nullOptionalWith analogs_detail: its oil EUR, bbl, from the decline fit on its actual cumulative oil at every 30-day ip_day it has produced (
analogs.eur); null when it can't be fit.Null when the well lacks production at any 30-day ip_day from 30 to 360 (its first 12 months), has a history longer than
eur_years, or the fit failed, and when the EUR is below its cumulative to date or not above its last 30-day cumulative (a flat extension, kept only after 90 days without production).eur_gasnumber or nullOptionalWith analogs_detail: its gas EUR, mcf, as
eur_oilis fit.inputsobjectOptionalWith analogs_detail: the model's raw inputs for this well, in
weightsorder.
coverageobject or nullRequiredHow often this model's analog spread held held-out wells' actual production, measured once when the index was built; null when the build has no held-out wells with production.
ShowHide 7 child fields
ip_dayintegerRequiredThe ip_day measured: the model's last one that enough held-out wells reach with production.
kintegerRequiredAnalogs per held-out well, as here.
nominalnumberRequiredThe share q10 to q90 would hold if it were a calibrated 80% interval.
measurednumber or nullRequiredThe share of held-out wells whose actual production at ip_day fell within their own analogs' q10 to q90, each against the training wells alone; to 0.001.
wellsintegerRequired≥ 0
Held-out wells measured (each with at least 5 analogs with production at ip_day).
gateobjectRequiredWhat the spread must pass to be shown.
ShowHide 3 child fields
minnumberRequiredLowest measured share shown.
maxnumberRequiredHighest measured share shown.
wellsintegerRequiredFewest held-out wells measured.
shownbooleanRequiredWhether
measuredandwellspass the gate, sospreadis given; withanalog_weights, only when the wells listed are the ones the model's weights list, as coverage was measured with those.
spreadobjectRequiredWith
coverage.shown, q10, q50 and q90 of these wells' actual cumulatives, each scaled to this well's lateral, asanalog_spread: an analog spread, not the model's uncertainty.{error}instead:- without
coverage.shown, saying what was measured; - with fewer than 5 analogs listed (
candidatesunder 5), whatevercoveragesays, saying how many training wells passed the filters; - with
analog_weights, unless the wells listed are the ones the model's weights list, since coverage was measured with the model's weights.
Same fields as AnalogSpread.
- without
analog_weightsobjectOptionalWith analog_weights, when it names some of this model's inputs: the weights sent for them, as sent; the distance then used
weights, these shares with the rest shared by the model's other inputs, or these rescaled to 1 when nothing takes the rest. Absent otherwise.inputsobjectOptionalWith analogs_detail: this forecast's own inputs, as each well's, so a table can put this well first.
eurobjectOptionalWith analogs_detail: how the wells'
eur_oilandeur_gaswere fit, or why there are none.ShowHide 2 variants
One of
The fit object
The fit.
basisstringRequiredIn words: the fit, the curves it ran on, the settings' source, what an analog needs to get an EUR (as ModelAnalogWell
eur_oilsays), how many got one and, by reason, how many didn't.declineobjectRequiredThe decline settings used: each well's own once a layer below the plan reaches any well with a setting other than
water; else a plan's own when it was made with eur: true, a forecast's decline with eur: true, else GET /dataset eur.defaults.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
fittedobjectRequiredHow many of the listed analogs got an EUR, per stream.
ShowHide 2 child fields
oilintegerRequired≥ 0
Analogs with an eur_oil.
gasintegerRequired≥ 0
Analogs with an eur_gas.
No EUR object
No EUR.
errorstringRequiredWhy there is no EUR: the server has none (as eur: true answers 503), or the fit failed.
No analogs object
No analogs.
errorstringRequiredWhy there are none, as the dataset has no analog index.
A stream that failed object
A stream that failed.
errorstringRequiredWhy this stream has no explanation.
gasobjectOptionalOne stream model's explanation of the forecast, or why it couldn't run.
Same fields as StreamExplanation.
waterobjectOptionalOne stream model's explanation of the forecast, or why it couldn't run.
Same fields as StreamExplanation.
No explanation object
No explanation.
designintegerRequired≥ 0
The design, as its index in
designs.errorstringRequiredWhy there is no explanation (no forecast).
scored_inputsarray of objectsOptionalOnly with include=scored_inputs on GET /plans/{id}/wells/{index}, never on POST /forecasts: what the models scored, one entry per design, in design order; a design with no model rows has nulls.
- Unlike
features(the spacing features at ip_day 1), these are the inputs at a day the models score, with each design's completions. Other days' values:GET /plans/{id}/wells/{index}/explanations/{design}?inputs=true, for the inputs that day's SHAP row lists. - On a set with several models, the first served stream's model's rows (oil, else gas, else water).
ShowHide 3 child fields in each item
designintegerRequiredThe design's position in the plan's
designs, from 0.ip_dayinteger or nullRequiredThe first model row's ip_day, the day
valuesis at. Null with no model rows.valuesobject or nullRequiredEach model input's value in that row, by feature name, in API units. Null with no model rows. A null inside means the input had no number or text in that row.
- Unlike
304 Unchanged since the ETag in If-None-Match.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 |
Shared errors400401403500503What they mean