Start a plan
Starts a development plan as a background job and answers 202 with its Location.
Start a plan
/plansStarts a development plan as a background job and answers 202 with its Location. A plan runs up to GET /dataset limits.plan_wells forecasts (wells × completion designs): 10,000 by default, so 5,000 wells with two designs.
What you send
wells, a layout the server lays out, or up to 100 layouts, their wells one after another (each echoed in layouts with first, its first well's plan index). from_plan runs a done plan's request again on the set's current models; assumption_set fills fields the body leaves out. The body may be up to 64 MB.
Waiting
GET /plans/{id}?wait=25 until status is done or error; each answer waits for the status to change. With an Idempotency-Key, a retry returns the plan the first request started.
Options
Each is described on its field.
eur: trueadds aneurstep: every forecast carrieseur, totals add each stream's EUR sum and count, and the export's forecast.csv adds EUR columns.bands: truegives every forecast its P10/P90 bands, summed in totals; withband_eur: true, totals addp10andp90EUR.- With TIL dates (
til_dateon a well, pad, layout, scenario or the plan), wells space as parents and children in date order, and totals addby_date, each stream by calendar month. per_well_errors: truefails a well that can't be placed on its own.dry_run: truechecks and counts the plan (PlanDryRun) without starting it. Wells aren't placed until a plan runs; POST /tvd-estimates gives the TVD a plan would estimate.
Scenarios
With a scenario on every well, or on every layout, up to 20 alternatives run in one plan, each scenario's wells spacing against only each other and existing wells. totals come per scenario and design, GET /plans/{id}/stats takes group_by=scenario or scenario, an export or economics reference takes one scenario at a time, and GET /plans/{id}/export answers 409.
Depletion chain
A dated plan chains depletion by default where GET /dataset depletion_chain.available is true: a planned well's P50 feeds the neighbor-production features of the later-month plan wells it is a parent of, and the plan echoes depletion_chain. See depletion_chain.
Chunks and queue
Wells run in spatial chunks of about 1,000, each with the plan wells within the spacing radius around it. Plans queue, oldest first, for a server task with room: a task runs at most 80,000 forecasts in plans at once, or limits.plan_wells + 10,000 where that is more. A queued plan reads running, with progress, done and every steps count 0, until a task takes it; a create never answers 409 for server load.
Limits
limits.plan_wells is at most 100,000. Once a caller has a plan queued or running, a new plan that would take their unfinished forecasts (wells × designs, across model sets) past GET /dataset limits.plan_unfinished_forecasts answers 429 with Retry-After; a caller with nothing unfinished is always accepted. The caller is the request's user, or the server without sign-in. Plans being deleted don't count, and a dry run is never refused.
Server tasks
Where a plan runs and is kept.
- With a state store and Redis, any task takes queued plans and answers GET,
wait, PATCH and DELETE for any plan. A DELETE stops a plan running on another task after its chunks in flight. - A plan running on another task answers GET with its progress; with
include=wellsit lists no wells until done (withRetry-After: 1), and asortis a 409 until then. - A plan with
callback_urlruns on the task that took it, and may start before older queued plans. - With a state store, a finished plan is read back from the store. Without one, plans don't survive a restart (GET /health
uptime_sstarts from 0): keep a deadline and create the plan again on a 404.
Callbacks
With callback_url, the server POSTs {"type": "plan.done" | "plan.failed", "plan": <the plan, as GET /plans/{id} returns it without include, less callbacks>} once the plan is done or fails; a plan deleted while running sends nothing.
- It goes as an export's callback does (POST /exports): the same host allowlist (GET /export-formats
callbacks, whoseeventslist only export events; 400 while callbacks are off), https and public addresses only. - 3 retries after 2 s, 15 s and 60 s, with the same
X-Export-Event,X-Export-DeliveryandX-Export-Signatureheaders, plusX-Plan-Id. - A plan takes one URL; its
callbacksshows the delivery, the URL as its origin. - The payload has the totals but no wells: page them with GET /plans/{id}?include=wells, or export the plan with a
callback_urlof its own and download it within the export's time to live.
Retention
With a state store, an unsaved plan is kept for the server's scratch period after it is made (90 days unless the server sets another; storage.expires_at says when) and deleted within a minute of expires_at; a saved plan is kept until deleted. Saving clears expires_at; unsaving starts a new scratch period. A deleted plan is gone from the API at once, its shares revoked and its attached documents deleted.
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.
Header parameters
Idempotency-KeystringOptionalpattern ^[A-Za-z0-9._:-]{1,128}$
Makes a retry safe: send your own key (a UUID, or your request id) and the same key on every retry. Without the header, nothing changes.
The same key and body (compared as JSON, key order ignored) within 24 hours replays what the first request made, with its id, in its current state, with
Idempotent-Replayed: true, and starts nothing. A different body is a 409 (details.fieldIdempotency-Key).- Keys are per operation, and only a success records one: retry a 502, 503, 504 or a lost response with the same key.
- With Redis, POST /saved/{collection}, /forecast-sources and /area-sets keep keys there, as do POST /plans and /exports on a server with a state store: every server task shares them and a restart keeps them. While Redis isn't answering, these answer 503.
- A retry while the first request is still being made waits up to 30 s for it, then answers 409: retry shortly with the same key.
- A key the first request hasn't recorded within a minute (its task stopped, or Redis failed as it finished) lapses; a retry then makes the resource again.
- Otherwise keys live in the server process's memory, the latest 1,000 per operation: a restart (a deploy is one) forgets them, and a retry during the first request waits for it.
- POST /forecasts with
async: trueand POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans withdry_run: trueneither keeps nor replays its key. - A replay of a plan or export the server has dropped is a 404.
Request body
application/json
Plan wells, a layout or layouts, and options.
wellsarray of objectsOptional1 to 100000 items
Plan wells (required unless
layoutorlayoutsis sent); up to the server's GET /datasetlimits.plan_wells(10,000 by default, at most 100,000) divided by the number of designs.ShowHide 22 child fields in each item
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 nullOptionalTarget formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD.
tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.
landing_below_top_ftnumber or nullOptional> -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] or nullOptionalWhere the lateral starts, [lng, lat], when not at
shl, the surface hole; absent or null, it starts atshl.shlmust be within 50,000 ft of it.With it, the lateral length and its 100 to 50,000 ft check, spacing, gun barrel laterals, PDP wells and model analogs run from heel to bhl. Subsurface grids still sample at
shlandbhlas the set'ssubsurface_samplingsays, and structure tops, landing, TVD estimates, the KB elevation and the model's surface hole inputs stay atshl.typed_lateralobject or nullOptionalA lateral length typed for the well, as an inventory file gives it:
length_ft, and theheel(the well's heel, else itsshl) andbhlit was typed for.The model gets
length_ftasnovi_lateral_length, and spacing, the completion totals, analogs, normalize_lateral_ft and pricing use it, while the well's heel (else shl) and bhl equal those two exactly and it is within 5% of the length measured between them or within 100 to 50,000 ft; otherwise the measured length. A client that moves an end can send it unchanged: the well then uses the measured length.Reads give the length used as
lateral_length_ft, withlateral_length_source. Optional: absent or null, the measured length.POST /inventories/read sets it from a file's stated length unless that is both more than 5% off the drawn one and outside 100 to 50,000 ft, with an issue when it is more than 5% off.
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].
lateral_outsidestring or nullOptionalIgnored; accepted so POST /layouts/fill wells with lateral_check can be sent as they are.
"above""below"landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.
The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.
The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.
Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.
Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:
- its formation has no grid there or no place in the column;
- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
- top and base averaged over the ends are under a foot apart: the zone pinches out.
A well's inputs echo it when it was sent.
lateral_length_ftnumber or nullOptionalIgnored: the lateral runs from heel, else shl, to bhl, unless
typed_lateralapplies. Accepted so POST /layouts/fill wells can be sent as they are.til_datestring or nullOptionalFormat
dateTIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.
From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.
partinteger or nullOptionalIgnored, as is bench: accepted so POST /layouts/fill wells can be sent as they are.
Show all 22 fields
benchinteger or nullOptionalIgnored.
padnumber or string or nullOptionalThe pad the well is on: a whole number, as POST /layouts/fill numbers them, or text of 1 to 60 characters, trimmed; 1 and "1" are one pad.
POST /plans keeps a valid key whenever sent, for
group_by=padand thepad=filter, and doesn't echo it on wells; other requests read it only withpads. It is checked (a 400 on a bad value) only withpads; withoutpads, a value that isn't a pad is ignored.scenariostringOptional1 to 60 characters
The alternative the well is in: a scenario's wells space against only each other and existing wells, never another scenario's. A name of 1 to 60 characters, trimmed.
Equal names (exact, case-sensitive) are one scenario; with pdp false its wells space against only each other. Give every well a scenario, or none (400 at the first without one). At most 10 scenarios on POST /forecasts, each its own spacing run, and 20 on POST /plans (400 at the first well past it, with details.max and details.count). Designs and pdp apply to every scenario unless
scenariossets its own.fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
This well's fluid in bbl per lateral ft.
Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in
padsor its layout (the bench or formation entry, then overall), its entry inscenarios(formation entry, then overall), the design'sformationsentry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds
resolvedto every well'sinputsin the request.proppant_lb_per_ftnumber or nullOptional> 0, < 20000
This well's proppant in lb per lateral ft.
Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in
padsor its layout (the bench or formation entry, then overall), its entry inscenarios(formation entry, then overall), the design'sformationsentry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds
resolvedto every well'sinputsin the request.stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.declineobjectOptionalEUR settings for this well; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.ShowHide 7 child fields
eur_yearsintegerOptional≥ 10, ≤ 50
Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.
terminal_declinenumberOptional≥ 0.01, ≤ 0.2
Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.
b_minnumberOptional≥ 0, ≤ 2.5
Lowest hyperbolic b the fit may use; below b_max.
b_maxnumberOptional≥ 0, ≤ 2.5
Highest hyperbolic b the fit may use; above b_min.
oilobjectOptionalOil's own settings over these.
ShowHide 3 child fields
terminal_declinenumberOptional≥ 0.01, ≤ 0.2
Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.
b_minnumberOptional≥ 0, ≤ 2.5
Lowest hyperbolic b the fit may use; below b_max.
b_maxnumberOptional≥ 0, ≤ 2.5
Highest hyperbolic b the fit may use; above b_min.
gasobjectOptionalGas's own settings over these.
Same fields as StreamDeclineSettings.
waterobjectOptionalWater's own settings over these, only with eur_water: true, else a 400. Unlike oil and gas it doesn't set per-stream settings: oil and gas keep theirs and their calls.
Same fields as StreamDeclineSettings.
namestring or nullOptionalup to 60 characters
Your name for the well, 1 to 60 characters once trimmed, on POST /plans, POST /forecasts and POST /inventories/write; other routes that take wells answer 400. null is none; a blank name is a 400.
Names needn't be unique. Reads show it beside
label, which stays Plan well N (Drawn well N on POST /forecasts). A plan's export tables put it in theirwellcolumn, keeping their row order, with a leading quote where a spreadsheet would read it as a formula. ARIES heads the well with it, unquoted, and sorts by header, so wells with one name share a header: sendaries.well_key: idto keep them apart.
layoutobjectOptionalInstead of wells: a fill boundary the server lays the plan's wells out in, up to GET /dataset
limits.plan_wellsdivided by the number of designs and at most 10,000, a fill's own limit.ShowHide 22 child fields
Send exactly one of:
areaorpolygon.Send exactly one of:
spacing_ftandformationorbenches.polygonarray of [number, number]sOptional3 to 500 items
Area corners, in order (closing point optional). Edges that cross are a 400.
azimuth_degnumberOptionalDefault
0≥ -360, ≤ 360Direction wells are drilled, degrees clockwise from north.
spacing_ftnumberOptional≥ 100, ≤ 10000
Distance between wells, ft.
lateral_length_ftnumber or nullOptional≥ 1000, ≤ 30000
Lateral length, ft; null or absent runs each well edge to edge.
setback_ftnumber or nullOptionalDefault
0≥ 0, ≤ 2640Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).
areaobjectOptionalInstead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is).
ShowHide 2 variants
One of
A polygon object
A polygon.
typeanyRequiredAlways
"Polygon"One part.
coordinatesarray of arraysRequiredat least 1 itemsItems at least 3 items
The outer ring, then its holes.
A multipolygon object
A multipolygon.
typeanyRequiredAlways
"MultiPolygon"Several parts, taken together.
coordinatesarray of arraysRequiredat least 1 itemsItems at least 1 items
The parts.
setback_end_ftnumber or nullOptional≥ 0, ≤ 2640
Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.
min_lateral_ftnumber or nullOptional≥ 1000, ≤ 30000
Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.
A kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.
standoff_ftnumber or nullOptional≥ 0, ≤ 5280
Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.
wells_per_padinteger or nullOptional≥ 1, ≤ 50
Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.
A fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's
wellswithpads. POST /plans keeps pad keys: withlayout, the 1-based pad number as text; withlayouts, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echopads) as a plan scenario'swellsin POST /economics.benchesarray of objectsOptional1 to 10 items
Instead of spacing_ft: benches laid out together, each landed in its own formation, at its own tvd_ft, landing_below_top_ft or landing_fraction. Not with the layout's formation, tvd_ft, landing_below_top_ft or landing_fraction.
ShowHide 13 child fields in each item
Send exactly one of:
spacing_ftorwells_per_section.formationstringRequiredThe bench's formation (case-insensitive): its wells land in it, and standoff_ft stands off its laterals.
spacing_ftnumberOptional≥ 100, ≤ 10000
Distance between the bench's wells, ft. Not with wells_per_section.
wells_per_sectionnumberOptional≥ 0.528, ≤ 52.8
Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).
offset_ftnumber or nullOptionalDefault
0≥ -10000, ≤ 10000Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.
Lines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.
tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.
landing_below_top_ftnumber or nullOptional> -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).landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.
The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.
The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.
Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.
Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:
- its formation has no grid there or no place in the column;
- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
- top and base averaged over the ends are under a foot apart: the zone pinches out.
A well's inputs echo it when it was sent.
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Fluid in bbl per lateral ft for the bench's wells: over the layout's, echoed as layer pad_formation. Needs one design, or none.
proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft for the bench's wells, as fluid_bbl_per_ft is set.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.declineobjectOptionalEUR settings for the bench's wells, as layer pad_formation; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
formationstringOptionalTarget formation every laid-out well lands in (case-insensitive; GET /formations lists them). Required without benches; not with them.
Show all 22 fields
tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.
landing_below_top_ftnumber or nullOptional> -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).landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.
The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.
The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.
Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.
Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:
- its formation has no grid there or no place in the column;
- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
- top and base averaged over the ends are under a foot apart: the zone pinches out.
A well's inputs echo it when it was sent.
til_datestringOptionalFormat
dateTIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.
From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Fluid in bbl per lateral ft for the layout's wells: below a bench's and above a scenario's and the design's, echoed as layer pad. Works with
benches. Needs one design, or none. A layout alone echoes notil_dateorlandingininputs.resolved; completions here turn on its completion keys.proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft for the layout's wells, as fluid_bbl_per_ft is set.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.declineobjectOptionalEUR settings for the layout's wells, as layer pad; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
layoutsarray of objectsOptional1 to 100 items
Instead of wells or layout: layouts whose wells the plan takes one after another, up to GET /dataset
limits.plan_wellsdivided by the number of designs in all, each at most 10,000 (a fill's own limit).- All layouts share one work limit (about a second). Each evens out as POST /layouts/fill does, with the work the plan's fills leave, unless any layout has a bench with a non-zero offset_ft: then none does, so a stagger set across layouts holds.
- Errors name layouts[i]. Past the plan's wells in all: a 400 on layouts[i] with details.max (the plan's wells), details.before (wells the layouts before it laid out) and details.count (its own).
ShowHide 23 child fields in each item
Send exactly one of:
areaorpolygon.Send exactly one of:
spacing_ftandformationorbenches.polygonarray of [number, number]sOptional3 to 500 items
Area corners, in order (closing point optional). Edges that cross are a 400.
azimuth_degnumberOptionalDefault
0≥ -360, ≤ 360Direction wells are drilled, degrees clockwise from north.
spacing_ftnumberOptional≥ 100, ≤ 10000
Distance between wells, ft.
lateral_length_ftnumber or nullOptional≥ 1000, ≤ 30000
Lateral length, ft; null or absent runs each well edge to edge.
setback_ftnumber or nullOptionalDefault
0≥ 0, ≤ 2640Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).
areaobjectOptionalInstead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is).
Same fields as UnitArea.
setback_end_ftnumber or nullOptional≥ 0, ≤ 2640
Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.
min_lateral_ftnumber or nullOptional≥ 1000, ≤ 30000
Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.
A kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.
standoff_ftnumber or nullOptional≥ 0, ≤ 5280
Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.
wells_per_padinteger or nullOptional≥ 1, ≤ 50
Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.
A fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's
wellswithpads. POST /plans keeps pad keys: withlayout, the 1-based pad number as text; withlayouts, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echopads) as a plan scenario'swellsin POST /economics.benchesarray of objectsOptional1 to 10 items
Instead of spacing_ft: benches laid out together, each landed in its own formation, at its own tvd_ft, landing_below_top_ft or landing_fraction. Not with the layout's formation, tvd_ft, landing_below_top_ft or landing_fraction.
ShowHide 13 child fields in each item
Send exactly one of:
spacing_ftorwells_per_section.formationstringRequiredThe bench's formation (case-insensitive): its wells land in it, and standoff_ft stands off its laterals.
spacing_ftnumberOptional≥ 100, ≤ 10000
Distance between the bench's wells, ft. Not with wells_per_section.
wells_per_sectionnumberOptional≥ 0.528, ≤ 52.8
Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).
offset_ftnumber or nullOptionalDefault
0≥ -10000, ≤ 10000Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.
Lines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.
tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.
landing_below_top_ftnumber or nullOptional> -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).landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.
The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.
The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.
Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.
Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:
- its formation has no grid there or no place in the column;
- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
- top and base averaged over the ends are under a foot apart: the zone pinches out.
A well's inputs echo it when it was sent.
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Fluid in bbl per lateral ft for the bench's wells: over the layout's, echoed as layer pad_formation. Needs one design, or none.
proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft for the bench's wells, as fluid_bbl_per_ft is set.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.declineobjectOptionalEUR settings for the bench's wells, as layer pad_formation; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
formationstringOptionalTarget formation every laid-out well lands in (case-insensitive; GET /formations lists them). Required without benches; not with them.
Show all 23 fields
tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.
landing_below_top_ftnumber or nullOptional> -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).landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.
The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.
The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.
Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.
Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:
- its formation has no grid there or no place in the column;
- no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
- the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
- top and base averaged over the ends are under a foot apart: the zone pinches out.
A well's inputs echo it when it was sent.
til_datestringOptionalFormat
dateTIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.
From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Fluid in bbl per lateral ft for the layout's wells: below a bench's and above a scenario's and the design's, echoed as layer pad. Works with
benches. Needs one design, or none. A layout alone echoes notil_dateorlandingininputs.resolved; completions here turn on its completion keys.proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft for the layout's wells, as fluid_bbl_per_ft is set.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.declineobjectOptionalEUR settings for the layout's wells, as layer pad; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
scenariostringOptional1 to 60 characters
Every one of the layout's wells' scenario: send one on every layout, or on none. Layouts may share one, a development across units.
designsarray of objectsOptional1 to 10 items
Completion designs; every well is forecast with each. Leave out for one design at the recent-completions median. A well's own completions, a scenario's and a pad's or layout's need one design.
ShowHide 7 child fields in each item
namestring or nullOptionalup to 60 characters
Your name for the design; defaults to Design 1, Design 2, ….
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.formationsarray of objectsOptionalPer-formation overrides, each formation at most once.
ShowHide 6 child fields in each item
formationstringRequiredFormation (case-insensitive).
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.
scenariosarray of objectsOptional1 to 20 items
Values for each scenario's wells, keyed by the
scenariothe wells name; a scenario without an entry takes the request's values.A well's own completions,
til_dateand landing beat its scenario's, as do its pad's and its layout's or bench's. A scenario's completions beat the design's, and itstil_dateandpdpthe request's. Once an entry sets completions, every well'sinputs.resolvedgives them. Once one sets a TIL date or landing that a well takes,inputs.resolvedgives each well'stil_dateandlanding, and the export's wells table addstil_date,til_layerandlanding_layer.A 400 naming the entry refuses a name no well has, a repeated name,
scenarioswhen no well has a scenario, and completions in it under more than one design.ShowHide 10 child fields in each item
namestringRequired1 to 60 characters
The scenario these values are for: exactly a name on the request's wells or layouts, trimmed, at most 60 characters, each once.
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Fluid in bbl per lateral ft for the scenario's wells: below a well's own, its pad's and a
formationsentry here, above the design's values. Needs one design, or none.proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft for the scenario's wells, as fluid_bbl_per_ft is set.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.til_datestring or nullOptionalFormat
dateTIL date for the scenario's wells without their own or their pad's or layout's, over the request's til_date.
TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.
From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.
pdpboolean or nullOptionalWhether this scenario's wells space against existing (PDP) wells, over the request's
pdp, so scenarios in one request can differ.declineobjectOptionalEUR settings for the scenario's wells; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
formationsarray of objectsOptionalup to 100 items
Values for the scenario's wells in one formation, each formation at most once. The only place a scenario sets landing.
ShowHide 10 child fields in each item
formationstringRequiredFormation (case-insensitive; GET /formations lists them).
fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Fluid in bbl per lateral ft for this formation's wells in the scenario or pad, over the entry's own. Needs one design, or none.
proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft, as fluid_bbl_per_ft is set.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft. Landing falls through as one unit: a well, or a narrower layer, that sets any of tvd_ft, landing_below_top_ft or landing_fraction keeps its own, so this reaches only wells that set none.
landing_below_top_ftnumber or nullOptional> -40000, < 40000
Instead of tvd_ft: ft below the formation top, as on a well.
landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.
declineobjectOptionalEUR settings for this formation's wells in the scenario or pad; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
padsarray of objectsOptionalat least 1 items
Values for each pad's wells, keyed by the
padthe wells name; a well on no listed pad takes the layers below. An entry may hold onlypadandname.A well's own completions,
til_dateand landing beat its pad's, an entry'sformationsbeat its own values, and a pad beats its wells' scenarios. Once an entry sets completions, every well'sinputs.resolvedgives them. Once one sets a TIL date or landing that a well takes,inputs.resolvedgives each well'stil_dateandlanding, and the export's wells table addstil_date,til_layerandlanding_layer.A 400 naming the field refuses:
- a pad no well has, or a repeat (1 and "1" are one pad);
- a bad
padon any well; - over 200,000
formationsentries across the list; padswithlayoutorlayouts, whose own fields set their wells;- a well with no formation that takes
landing_below_top_ftorlanding_fractionfrom an entry's own values; - completions in it under more than one design.
ShowHide 13 child fields in each item
padinteger or stringRequired1 to 60 characters
The pad these values are for: an integer or text as the wells name it, trimmed, at most 60 characters, each once; 1 and "1" are one pad.
namestring or nullOptionalup to 60 characters
The pad's name, 1 to 60 characters once trimmed; null is none, and a blank name is a 400. Names needn't be unique: the key still groups and orders pads, pairs them in comparisons and filters with
pad=.POST /plans keeps it: the economics export's
padcolumn writes it instead of the key on well and pad rows, GET /plans/{id}/stats?group_by=pad gives it asgroups[].name, GET /plans/{id}/rollup aspads[].name, and the type curve, plan economics and comparisons by pad give it beside the key. POST /forecasts and POST /exportssourcecheck it but don't use it.fluid_bbl_per_ftnumber or nullOptional> 0, < 1000
Fluid in bbl per lateral ft for the pad's wells: below a well's own and a
formationsentry here, above a scenario's and the design's. Needs one design, or none.proppant_lb_per_ftnumber or nullOptional> 0, < 20000
Proppant in lb per lateral ft for the pad's wells, as fluid_bbl_per_ft is set.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.til_datestring or nullOptionalFormat
dateTIL date for the pad's wells without their own, over a scenario's and the request's til_date.
TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.
From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.
tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft for the pad's wells. Landing falls through as one unit, so a well, or a
formationsentry here, that sets any landing field keeps it.landing_below_top_ftnumber or nullOptional> -40000, < 40000
Instead of tvd_ft: ft below the top of each well's own formation; a well that takes it needs one.
landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: 0 at the top of each well's own formation to 1 at its base; a well that takes it needs one.
declineobjectOptionalEUR settings for the pad's wells; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
formationsarray of objectsOptionalup to 100 items
Values for the pad's wells in one formation, each formation at most once.
Same fields as ScenarioFormationInput.
formationsarray of objectsOptionalup to 100 items
The request's landing per formation, each formation at most once; a landing on the well, its pad, layout, bench or scenario entry beats it. Goes with
wells,layoutorlayouts.An entry for a formation no well has is accepted. Completions per formation stay in
designs. Once an entry sets a landing that a well takes,inputs.resolvedgives each well'stil_dateandlanding, and the export's wells table addstil_date,til_layerandlanding_layer.ShowHide 5 child fields in each item
formationstringRequiredFormation (case-insensitive; GET /formations lists them).
tvd_ftnumber or nullOptional> 0, < 40000
True vertical depth in ft for the request's wells in this formation that no narrower layer lands.
landing_below_top_ftnumber or nullOptional> -40000, < 40000
Instead of tvd_ft: ft below the formation top, as on a well.
landing_fractionnumber or nullOptional≥ 0, ≤ 1
Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.
declineobjectOptionalEUR settings for the request's wells in this formation; needs
euron.With
euroff, adeclineon any layer is a 400, even{}or one that reaches no well, though either sets nothing. POST /exportssourceturnseuron when it is left out.Each field takes the narrowest value set: the well's; its pad's or layout's,
formationsentry or bench first; its scenario's,formationsentry first; the request'sformationsentry; the request'sdecline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well'sb_maxbeats a plan'soil.b_max. Once a value reaches a well, every well'sinputs.resolved.declinegives each value and its layer, and the export's wells table adds them.A well whose
b_minresolves at or above itsb_maxis a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economicsforecastrefuse adecline.Same fields as DeclineSettings.
pdpbooleanOptionalDefault
trueSpace against existing (PDP) wells. A scenario's
pdpinscenariosbeats it, and this stays the plan's echoedpdp.namestring or nullOptionalup to 100 characters
Your name for the plan.
eurbooleanOptionalDefault
falseAdd the EUR (Novi type-curve decline fit) to each oil and gas forecast; GET /dataset eur says whether this server has it (503 if not).
eur_waterbooleanOptionalDefault
falseFit water's EUR too, with
decline.waterover the settings at any layer.Adds
eurto each water forecast,waterto thedeclineecho,totals[].eurandinputs.resolved.decline, and water's columns to the eur, forecast and wells tables, where monthly water runs to the EUR day. BOE never reads it, and oil's and gas's fits are unchanged. Without it,decline.wateris a 400. Needseur: true(a 400 on eur_water without it).declineobjectOptionalDecline fit settings, with eur: true only; any left out take Novi's defaults (GET /dataset eur.defaults), and oil and gas (with eur_water, water) override them per stream. The plan layer: a well, pad, layout, bench, scenario or
formationsentry can set its wells' own, field by field.Same fields as DeclineSettings.
Show all 21 fields
til_datestringOptionalFormat
dateTIL (first production) date, YYYY-MM-DD, for every well no narrower layer dates: from GET /dataset as_of to 30 years from today. Echoed in each such well's inputs.
bandsbooleanOptionalDefault
falseAdd P10/P90 bands to each stream forecast (Novi's predrill bands, same model call); GET /dataset bands says which streams have them, and a request answers 503 when none has.
band_eurbooleanOptionalDefault
falseAlso fit each oil and gas band to an EUR with the decline settings, and water's with eur_water: two more decline fits per such forecast (about three times eur's fitting). Needs bands and eur.
callback_urlstring or nullOptionalup to 2048 characters
Where to POST the plan once it is done or fails: https, to a host the server allows (GET /export-formats callbacks). See POST /plans.
depletion_chainbooleanOptionalFeed each planned well's P50 production to the plan wells it is a parent of, those with a later TIL month. On by default where GET /dataset depletion_chain.available is true, else off. Only plans take it.
- A well whose planned parent is TIL in an earlier calendar month is re-forecast after it, wave by wave, each design on its own parents' P50. A parent read past its 1,080-day forecast is extended with the plan's decline settings (Novi's defaults without eur).
- Existing (PDP) parents' production is as GET /dataset depletion_chain.neighbor_production says.
- false: a planned parent's production reads as 0 in every neighbor-production feature (novi_spacing_sum_prior_* and novi_spacing_delgados_p*), so neighbor production is existing wells' history alone.
- With available false, the plan runs as without it, and with true sent its echo says why.
- Each wave adds a production pass and a forecast per design, so deep chains take longer.
steps.chaincounts the waves' passes running, and a chained well finishes once its last design's wave lands.
dry_runbooleanOptionalDefault
falseWith true, only check and count: the same checks as a create and a 200 with PlanDryRun, with nothing started (no job, no callback). false or absent: a plan.
An Idempotency-Key is neither kept nor replayed. Wells aren't placed, so a well whose TVD can't be estimated or whose landing can't be placed answers 200 here and fails once the plan runs (only that well with per_well_errors: true, unless no well can be placed).
per_well_errorsbooleanOptionalDefault
falseWith true, a well whose TVD or landing can't be placed fails alone; the plan ends in error only when no well can be placed. Without it, one placement failure fails the whole plan.
- The plan lists failed_wells. The well's summary has error {field, message}, error forecasts and no estimates or spacing; reading it or its explanations is a 409. Stats count it as missing; exports keep its reason with blank placement columns.
- Its plan neighbors are spaced and forecast without it, as if it were never drilled: less interference, so their forecasts may read high.
- For the like-for-like plan, run the wells again with this one placed: tvd_ft for its landing_fraction or landing_below_top_ft, and a target formation if it has none (a plan built from a layout goes as its well list, so only this well changes).
- Economics leaves any scenario holding it unpriced (economics null, reason naming the first well without flows); list the placed wells in plan.wells to price them.
- Worker or internal errors still fail the plan.
from_planstringOptionalFormat
uuidInstead of wells, layout or layouts: a done plan's id. The new plan runs its stored request again on the model set's current models, and echoes
from_plan.- It keeps the wells where they were (a layout's aren't laid out again), designs,
pdp, decline and EUR settings, bands, depletion chain,per_well_errorsand its start day, which undated wells take. - Only
name,callback_urlanddry_rungo with it; any other field is a 400 naming it. A plan you can't see on this model set is 404; one running or failed is 409. - POST /comparisons of the two names the release and model set each ran on, so a difference comes from the models or the release, not the inputs.
- It keeps the wells where they were (a layout's aren't laid out again), designs,
assumption_setobjectOptionalA saved assumption set: each plan field it holds that this body leaves out or sends as null is filled from it before the body is checked, unless
clearnames it; a field the body sends wins.- It fills designs, formations, til_date, pdp, depletion_chain, eur, eur_water, decline, bands and band_eur, never its pad_template or economics (not plan fields). A 400 on a filled field names it and starts "From assumption set {name} (version {n}):".
- A set you can't read is 404; one made on another model set, a 400 on assumption_set naming both; without a state store, 409; with from_plan, 400.
- The plan echoes assumption_set with the version run and the fields filled; GET /plans/{id}?include=request answers the body after the fill.
- Without one, a plan runs on the dataset's defaults (Novi defaults) and has no assumption_set echo.
ShowHide 3 child fields
idstringRequiredFormat
uuidAn assumption set's id, from POST /saved/assumption-sets.
versionintegerOptional≥ 1
The version you read; another one is a 409 whose details.version is the current one. Left out, the current version.
cleararray of strings or nullOptionalSet values the fill skips: til_date, eur or both. Absent, null or []: the set fills as without it.
- til_date: the set's start date, so wells this body doesn't date run undated.
- eur: the set's eur, eur_water, decline and band_eur, and each filled formations entry's decline, so the plan runs without EUR; bands and those entries' landings still fill.
- A field this body sends still wins: a til_date sent beside it runs on that date, and "eur": true runs EUR on this body's own settings.
- A name the set doesn't hold is ignored, so you needn't read the set first; a name may repeat. Any other value is a 400 on assumption_set.clear.
- assumption_set.filled leaves out what the set didn't fill.
"til_date""eur"
Responses
With dry_run: true: the plan a create would start, counted; nothing was started.
dry_runanyRequiredAlways
trueAlways true: nothing was started.
wellsintegerRequired≥ 1
Wells the plan would have: wells as sent, or laid out from layout or layouts.
designsintegerRequired≥ 1
Completion designs the plan would run, one when none is sent.
forecastsintegerRequired≥ 1
wells × designs, what GET /dataset
limits.plan_wellscaps.scenariosarray of objectsOptionalWhen the request sent scenarios: each, in the order its first well came, with its well count.
ShowHide 3 child fields in each item
namestringRequiredThe scenario.
wellsintegerRequired≥ 1
Its wells.
pdpbooleanOptionalThe scenario's own pdp; only when
scenariosset one. Without it the scenario ran with the request'spdp.
layoutobjectOptionalWhen the request sent layout: what it would lay out, as the plan would echo it.
ShowHide 14 child fields
countintegerRequiredWells.
azimuth_degnumberRequiredAzimuth used.
lateral_length_ftnumber or nullRequiredLength used, or null for edge to edge.
spacing_ftnumberOptionalSpacing used; left out with benches.
setback_ftnumberOptionalSetback used, ft; only when the request sent one.
setback_end_ftnumberOptionalEnd setback used, ft; only when sent.
min_lateral_ftnumberOptionalShortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out.
standoff_ftnumberOptionalStandoff used, ft; only when sent.
standoff_wellsintegerOptional≥ 0
With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.
wells_per_padintegerOptionalWells per pad; only when sent.
wells_per_sectionnumberOptionalWith benches: their wells_per_section added up, the unit's total.
padsarray of arraysOptionalWith wells_per_pad: each pad's wells, as indexes of the response's (or plan's) wells.
benchesarray of objectsOptionalWith benches: each bench as laid out.
ShowHide 6 child fields in each item
spacing_ftnumberRequiredSpacing used, ft.
wells_per_sectionnumberRequired5,280 ft / spacing_ft, or as sent.
offset_ftnumberRequiredOffset used, ft.
formationstring or nullRequiredThe bench's formation, or null when none was sent.
countintegerRequired≥ 0
Wells in the bench.
wellsarray of integersRequiredItems ≥ 0
The bench's wells, as indexes of the response's (or plan's) wells.
formationstringOptionalThe formation every well landed in, as GET /formations names it; left out with benches, which name their own.
layoutsarray of objectsOptionalWhen the request sent layouts: what each would lay out, in order, as the plan would echo them.
ShowHide 16 child fields in each item
firstintegerRequired≥ 0
The plan index of the layout's first well; its wells follow in order.
countintegerRequiredWells.
azimuth_degnumberRequiredAzimuth used.
lateral_length_ftnumber or nullRequiredLength used, or null for edge to edge.
scenariostringOptionalWhen the layout was sent with one: its scenario.
spacing_ftnumberOptionalSpacing used; left out with benches.
setback_ftnumberOptionalSetback used, ft; only when the request sent one.
setback_end_ftnumberOptionalEnd setback used, ft; only when sent.
min_lateral_ftnumberOptionalShortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out.
standoff_ftnumberOptionalStandoff used, ft; only when sent.
standoff_wellsintegerOptional≥ 0
With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.
wells_per_padintegerOptionalWells per pad; only when sent.
Show all 16 fields
wells_per_sectionnumberOptionalWith benches: their wells_per_section added up, the unit's total.
padsarray of arraysOptionalWith wells_per_pad: each pad's wells, as indexes of the response's (or plan's) wells.
benchesarray of objectsOptionalWith benches: each bench as laid out.
ShowHide 6 child fields in each item
spacing_ftnumberRequiredSpacing used, ft.
wells_per_sectionnumberRequired5,280 ft / spacing_ft, or as sent.
offset_ftnumberRequiredOffset used, ft.
formationstring or nullRequiredThe bench's formation, or null when none was sent.
countintegerRequired≥ 0
Wells in the bench.
wellsarray of integersRequiredItems ≥ 0
The bench's wells, as indexes of the response's (or plan's) wells.
formationstringOptionalThe formation every well landed in, as GET /formations names it; left out with benches, which name their own.
assumption_setobjectOptionalWhen the request sent assumption_set: the set, as the plan would echo it.
ShowHide 4 child fields
idstringRequiredFormat
uuidThe set's id.
versionintegerRequired≥ 1
The version the plan ran with.
namestringRequiredThe set's name then.
filledarray of stringsRequiredThe request fields the set filled, in the set's key order. A value they set reads in each well's resolved inputs as the field it filled (plan or plan_formation).
The plan, running (or, replaying an Idempotency-Key, as it is now).
idstringRequiredFormat
uuidPlan id.
namestring or nullRequiredPlan name.
statusstringRequiredrunning, then done or error.
"running""done""error"pdpbooleanRequiredWhether existing wells are in spacing.
totalintegerRequiredWells.
doneintegerRequiredWells finished; with per_well_errors, a well that could not be placed counts as finished.
progressnumberRequired≥ 0, ≤ 1
Share of the work done: wells weighted by the worker steps (spacing, spacing features, forecast) their chunks have finished; with per_well_errors, a well that could not be placed counts as finished.
created_atstringRequiredFormat
date-timeStart time.
secondsnumberRequiredRun time so far, or in total once finished.
designsarray of objectsRequiredThe completion designs every well runs with.
ShowHide 12 child fields in each item
indexintegerRequired≥ 0
Position in designs.
namestringRequiredName.
inputsobjectRequiredAs requested, blanks as null; the stage fields only where the set's models read them.
ShowHide 5 child fields
fluid_bbl_per_ftnumber or nullRequired> 0, < 1000
Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
proppant_lb_per_ftnumber or nullRequired> 0, < 20000
Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.
fluid_bbl_per_ftnumberRequiredFluid used, bbl/ft.
proppant_lb_per_ftnumberRequiredProppant used, lb/ft.
completions_sourcestringRequiredinput when both were entered, otherwise how the defaults were made.
formationsarray of objectsRequiredEvery formation the request's wells or the design name; wells without a formation use the design's own values.
ShowHide 9 child fields in each item
formationstringRequiredFormation.
inputsobjectRequiredAs requested, blanks as null; the stage fields only where the set's models read them.
ShowHide 5 child fields
fluid_bbl_per_ftnumber or nullRequired> 0, < 1000
Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
proppant_lb_per_ftnumber or nullRequired> 0, < 20000
Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.
stage_length_ftnumber or nullOptional> 0, < 2000
Stage length in ft.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.clusters_per_stagenumber or nullOptional> 0, < 100
Perforation clusters per stage; fractions are accepted.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.frac_rate_bbl_per_minnumber or nullOptional> 0, < 500
Frac pump rate in bbl per minute.
Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's
unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.
fluid_bbl_per_ftnumberRequiredFluid used, bbl/ft.
proppant_lb_per_ftnumberRequiredProppant used, lb/ft.
completions_sourcestringRequiredinput when both were entered, otherwise how the defaults were made.
stage_length_ftnumberOptionalStage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.
clusters_per_stagenumberOptionalClusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.
frac_rate_bbl_per_minnumberOptionalFrac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.
sourcesobjectOptionalHow each stage value used was found: input when the request set it, else the median's text.
ShowHide 3 child fields
stage_length_ftstringOptionalinput, or how the default was made.
clusters_per_stagestringOptionalinput, or how the default was made.
frac_rate_bbl_per_minstringOptionalinput, or how the default was made.
stage_length_ftnumberOptionalStage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.
clusters_per_stagenumberOptionalClusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.
frac_rate_bbl_per_minnumberOptionalFrac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.
sourcesobjectOptionalHow each stage value used was found: input when the request set it, else the median's text.
ShowHide 3 child fields
stage_length_ftstringOptionalinput, or how the default was made.
clusters_per_stagestringOptionalinput, or how the default was made.
frac_rate_bbl_per_minstringOptionalinput, or how the default was made.
unusedarray of stringsOptionalThe stage fields the request sent, on the design or any narrower layer, that the model set's models don't read, so nothing used them; only when there is one.
"stage_length_ft""clusters_per_stage""frac_rate_bbl_per_min"
errorobject or nullRequiredWhy the plan failed.
ShowHide 3 child fields
codestringRequiredMachine-readable code.
"invalid_argument""not_found""conflict""unavailable""internal"messagestringRequiredWhat went wrong and how to fix it.
detailsobjectRequiredContext:
fieldnames the input at fault, as wells[3].tvd_ft.ShowHide 1 child field
fieldstringOptionalThe input at fault.
totalsarray of objects or nullRequiredTotals per design, once done. On a plan made with scenarios, one per scenario and design, scenario by scenario in the order of
scenarios, each with itsscenario: there totals[d] is not design d.ShowHide 8 child fields in each item
designintegerRequired≥ 0
The design, as its index in
designs.wells_with_forecastintegerRequiredWells with a forecast.
wells_flaggedinteger or nullRequiredWells whose checks flagged inputs outside training; null when no well's inputs could be checked. A well whose only finding is
context(neighbors' production outside training) isn't counted. When wells_flagged is above 0, show the flag beside any total you quote, saying how many wells it covers.forecastobjectRequiredCumulative oil (bbl), gas (mcf) and water (bbl) by ip_day, or why the well has no forecast (no formation).
ShowHide 2 variants
One of
Forecasts per stream object
Forecasts per stream. 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.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.
errorstringRequiredWhy the well has no forecast.
scenariostringOptionalOn a plan made with scenarios: the scenario these wells are in. Scenarios are alternatives, so no total adds two.
wells_contextintegerOptional≥ 1
Wells whose checks list neighbors' production outside training in
context, flagged or not; absent when none.eurobjectOptionalWith eur: true, each stream's EUR summed over the wells with one, and BOE over the wells with both. 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.ShowHide 4 child fields
boeobjectRequiredBOE EUR over the wells with both fits, so the sum and the well count agree.
ShowHide 4 child fields
valuenumber or nullRequiredOil EUR plus gas EUR / 6 (bbl of oil equivalent) summed over the wells with both; null when none has.
wellsintegerRequiredWells with both an oil and a gas EUR.
p10objectOptionalWith boe and band_eur: each well's P10 oil EUR plus P10 gas EUR / 6, summed over the wells with both.
ShowHide 2 child fields
valuenumber or nullRequiredThis band's EUR summed over the wells with one; null when none has.
wellsintegerRequiredWells with this band's EUR.
p90objectOptionalWith boe and band_eur: each well's P90 oil EUR plus P90 gas EUR / 6, summed over the wells with both.
Same fields as BandEurTotal.
oilobjectOptionalA stream's EUR over the plan.
ShowHide 5 child fields
valuenumber or nullRequiredEUR summed over the wells with one; null when none has.
daysinteger or nullRequiredip_day of the EUR; null when none has one, or when the wells summed differ in eur_years: the sum then runs to no one day, and each scenario is read apart.
wellsintegerRequiredWells with an EUR.
p10objectOptionalWith band_eur: true, the P10 band's EUR over the plan.
Same fields as BandEurTotal.
p90objectOptionalWith band_eur: true, the P90 band's EUR over the plan.
Same fields as BandEurTotal.
gasobjectOptionalA stream's EUR over the plan.
Same fields as EurTotal.
waterobjectOptionalOnly with eur_water: true. BOE doesn't read it.
Same fields as EurTotal.
by_dateobjectOptionalWhen any well has a TIL date, from any layer: its streams summed by calendar date.
ShowHide 3 child fields
datesarray of stringsRequiredMonth starts from the earliest TIL date's month through the first one on or after the latest TIL date plus horizon_days.
horizon_daysintegerRequiredThe forecast horizon the dates run past the latest TIL: 1,080 days.
forecastobjectRequiredPer stream. 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.ShowHide 3 child fields
oilobjectOptionalOne stream's plan total by date, or why there is none.
ShowHide 2 variants
One of
Cumulative volumes by date object
Cumulative volumes by date.
valuesarray of numbersRequiredOne per date.
bandsobjectOptionalWith bands: true, the wells' P10s and P90s by date the same way, when 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 numbersRequiredOne per date.
p90array of numbersRequiredOne per date.
No total object
No total.
errorstringRequiredWhy this stream has no total (no well has its forecast).
gasobjectOptionalOne stream's plan total by date, or why there is none.
Same fields as ByDateStream.
waterobjectOptionalOne stream's plan total by date, or why there is none.
Same fields as ByDateStream.
Show all 33 fields
linksobjectRequiredRelated URLs.
ShowHide 3 child fields
selfstringRequiredThis plan.
wellsstringRequiredThis plan with its wells.
exportstringOptionalThe zip export; absent on a Legacy Forecast (origin.engine fe): export it with POST /exports.
storageobject or nullOptionalOnly with include=storage or on updatePlan. Null without a state store.
ShowHide 7 child fields
tenantstringRequiredOwning tenant.
savedbooleanRequiredKept until deleted when true.
expires_atstring or nullRequiredFormat
date-timeScratch expiry, null when saved.
created_atstringRequiredFormat
date-timeCreation time.
updated_atstringRequiredFormat
date-timeLast metadata update.
created_bystring or nullRequiredThe email of the user who posted the plan, as
created_byon saved documents. Null for older plans.sharesintegerRequired≥ 0
Active, unrevoked and unexpired share count.
requestobject or nullOptionalOnly with include=request: the body POST /plans accepted, keys as sent after an assumption set's fill, without callback_url and dry_run. A field sent as null comes back null unless the set filled it; a plan made with from_plan carries its source plan's body. Null for an older plan, one made through the legacy POST /api/plan, or one re-run from either.
Same fields as PlanRequest.
from_planstringOptionalFormat
uuidOnly on a plan made with from_plan: the plan whose stored request this one ran again.
assumption_setobjectOptionalOnly on a plan made with assumption_set, or with from_plan from one: the set it ran with.
Same fields as AssumptionSetEcho.
failed_wellsobjectOptionalPresent with per_well_errors, including while running and on error; a failed well's plan neighbors are spaced and forecast without it.
ShowHide 2 child fields
countintegerRequiredEvery well that could not be placed.
wellsarray of objectsRequiredup to 100 items
First failed wells, lowest index first.
ShowHide 3 child fields in each item
indexintegerRequiredPlan well index.
fieldstringRequiredPlacement field.
"tvd_ft""landing_below_top_ft""landing_fraction""formation"messagestringRequiredWhy the well could not be placed.
stepsobjectOptionalWhile running: chunks (up to 1,000 wells) in each worker step now.
ShowHide 5 child fields
spacingintegerRequiredChunks in spacing.
calcintegerRequiredChunks in the spacing feature step.
forecastintegerRequiredChunks in forecast.
eurintegerOptionalWith eur: true, chunks fitting EUR.
chainintegerOptionalWith depletion_chain applied: wave passes running (one design's production pass and re-forecast for up to 1,000 wells).
scenariosarray of objectsOptionalWhen the request sent scenarios: each, in the order its first well came, with its well count.
Same fields as ScenarioEcho.
layoutobjectOptionalWhen the request sent layout: what was laid out.
Same fields as LayoutEcho.
layoutsarray of objectsOptionalWhen the request sent layouts: what each laid out, in order.
Same fields as PlanLayoutEcho.
declineobjectOptionalWith eur: true, the plan's decline settings, which a well may override (
per_well).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
bandsobjectOptionalWith bands: true, the bands every forecast carries.
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).
depletion_chainobjectOptionalWith the chain on: depletion_chain true, or absent on a set whose models read neighbors' production. What the chain read and did.
ShowHide 8 child fields
appliedbooleanRequiredWhether the chain ran: false when no served model reads neighbors' production, and the plan then ran as without it.
reasonstring or nullRequiredWhy the chain didn't run; null when it did.
featuresarray of stringsRequiredThe served models' features the chain feeds, as GET /dataset depletion_chain lists them.
bucketsintegerRequired≥ 1
Calendar months the plan's TIL dates fall in. Wells without a til_date are TIL on the plan's start day.
wavesinteger or nullRequired≥ 0
Waves after the plan's first pass: a well with planned parents is re-forecast one wave after its deepest one. null until every well is spaced (0 from the start when every TIL is in one calendar month), or when not applied.
planned_parentsinteger or nullRequired≥ 0
Plan wells that are a parent of a later-month plan well, so their P50 feeds it. null until every well is spaced (0 from the start when every TIL is in one calendar month), or when not applied.
neighbor_productionstringRequiredWhere existing (PDP) parents' production came from:
historyis their production to the dataset's as_of, held flat after;extendedcontinues it with Novi's production forecast for each existing well past its history."history""extended"extensionobject or nullRequiredThe decline settings a planned parent was extended with where a later well reads it past its 1,080-day forecast (the plan's decline echo with eur, else Novi's defaults, and always the base settings for water, so never a
water); null while none has been. Withper_wellthese are the plan's, and a parent with its own settings was extended with those: read each well'sinputs.resolved.decline.Same fields as Decline.
callbacksarray of objectsOptionalup to 1 items
Only on a plan made with callback_url: its delivery, as an export's callbacks show theirs.
ShowHide 6 child fields in each item
urlstringRequiredWhere it goes: its origin, with /… for any path or query. The server keeps the whole URL, for delivery only.
statusstringRequiredpending until delivered or failed; a cancelled export's pending callbacks fail with no attempts, since nothing is sent.
"pending""delivered""failed"attemptsintegerRequired≥ 0
POSTs so far.
last_statusinteger or nullRequiredThe receiver's last HTTP status.
last_errorstring or nullRequiredWhy the last attempt failed.
delivered_atstring or nullRequiredFormat
date-timeWhen a 2xx came back.
wellsarray of objectsOptionalWith include=wells: the wells, or while running those finished so far.
ShowHide 14 child fields in each item
indexintegerRequired≥ 0
Position of the well in the request.
keystringOptionalKey the models use for the well, as DRAWN-<index>; other drawn wells appear among neighbors by this key.
labelstringOptionalDisplay name: Plan well N in a plan, Drawn well N from POST /forecasts, counting from 1.
inputsobjectOptionalThe 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.
Same fields as TypedLateral.
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_ftintegerOptionalThe 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.estimatesobjectOptionalThe TVD the models used, entered or estimated.
ShowHide 2 child fields
tvd_ftnumberRequiredTVD used, ft.
tvd_sourcestringRequiredinput, or how it was estimated.
forecastsarray of objectsOptionalOne 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.
Same fields as StreamForecast.
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.Same fields as BoeForecast.
No forecast object
No forecast.
designintegerRequired≥ 0
The design, as its index in
designs.errorstringRequiredWhy the well has no forecast.
spacingobjectOptionalSpacing summary.
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.
neighbor_countintegerRequiredSpacing neighbors.
errorobjectOptionalWith per_well_errors, the placement failure.
ShowHide 2 child fields
fieldstringRequiredPlacement field.
"tvd_ft""landing_below_top_ft""landing_fraction""formation"messagestringRequiredWhy the well could not be placed.
valuenumber or nullOptionalWith fields=value and sort: the sort metric's value, rounded to 0.1 in its unit; null for a well without one.
checksobject or nullOptionalOpt-in through fields=checks: the same object as forecasts[design].checks, default design 0; null when none, including failed wells. Show the flag beside any number quoted from a flagged well.
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.Same fields as InputOutOfRange.
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.
namestringOptionalThe name the request gave the well, trimmed; only when it gave one.
labeldoesn't change. Withfields, ask for it by name.nearest_same_formation_ftnumber or nullOptionalOpt-in through fields=nearest_same_formation_ft: the smallest
minxy, ft to 0.1, over the well's spacing neighbours in its own formation.The neighbours are the wells, planned or existing, whose lateral midpoints are within the spacing radius of the well (GET /dataset
spacing.search_radius_ft). Null when none is, so also when the nearest well in the formation is beyond that radius; when the well has no formation or could not be placed; and on older plans.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. Withfields, ask for it by name."typed""measured"
next_cursorstring or nullOptionalWith include=wells: cursor for the next page of wells, or while running for the wells that finish next.
matchedintegerOptional≥ 0
With include=wells and a
scenario,formation,qorpadthat filters: the wells passing them and anywells, finished or not, over every page. A failed plan returns no wells, and nomatched.originobjectOptionalWith
originon GET /plans orinclude=origin, and always on a Legacy Forecast: where the plan came from.ShowHide 2 variants
One of
A v2 plan object
A v2 plan.
engineanyRequiredAlways
"v2"A plan this API ran.
A Legacy Forecast object
A Legacy Forecast.
engineanyRequiredAlways
"fe"A Legacy Forecast, read only. Legacy Forecasts are dynamic imports from Forecast Engine v1.
job_idintegerRequiredThe run's job.
runstringRequiredThe run's name, as the date it ran and a number.
ran_atstringRequiredFormat
date-timeWhen the run was submitted.
indexed_atstringOptionalFormat
date-timeOn GET /plans rows: when the server last read the run into its index. A run read again, after its file changed or a read failed, has the later time.
created_fromkeeps a run whosecreated_atorindexed_atis at or after it.
streamsarray of stringsOptionalWith
origin: the streams the plan forecast, in oil, gas, water order; its forecasts and totals carry only these. Every stream on a v2 plan."oil""gas""water"stream_labelsobjectOptionalWith
origin, only where a stream holds something its name doesn't say:{"oil": "condensate"}on a run that forecast condensate, or on a v2 plan whose model set labels its oil slot condensate.ShowHide 1 child field
oilstringOptionalWhat the oil stream holds, as
condensate.
timingsobject or nullOptionalOnly with include=timings: where the plan's time went, from each finished chunk (up to 1,000 wells) and depletion chain wave pass. Null when nothing was timed: a queued plan, a Legacy Forecast or an older plan.
A running plan shows the chunks finished so far, as of its server's last heartbeat (every 30 s by default) when that is another server. A resumed plan counts each finished chunk and pass as the run that finished it timed it, except an older server's.
ShowHide 2 child fields
stepsobjectRequiredThe worker steps with a timed chunk, in this order.
ShowHide 5 child fields
spacingobjectOptionalThe TVD estimate, the subsurface grids and the spacing worker, which run while a chunk holds the spacing step.
ShowHide 4 child fields
chunksintegerRequired≥ 0
Chunks timed; for chain, wave passes; for wait, both.
secondsnumberRequired≥ 0
Their total, in seconds to 0.01.
p50_secondsnumberRequired≥ 0
The median chunk's seconds, the lower of the two middle ones for an even count.
max_secondsnumberRequired≥ 0
The longest chunk's seconds.
calcobjectOptionalThe spacing feature worker.
Same fields as PlanStepTimes.
forecastobjectOptionalThe forecast worker.
Same fields as PlanStepTimes.
eurobjectOptionalWith eur: true, the EUR fits once a chunk holds the eur step.
Same fields as PlanStepTimes.
chainobjectOptionalWith depletion_chain applied, each wave pass's work in its steps: the parents' extension, the production pass, the re-forecast and, with eur: true, its EUR fits.
chunkscounts passes.Same fields as PlanStepTimes.
waitobjectRequiredHow long each timed chunk and wave pass waited to enter its steps, all of them together: for another chunk or pass to leave a step and, for spacing, for room for its wells on the server.
Same fields as PlanStepTimes.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | The Idempotency-Key was already used with a different body; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key; or |
| 413 | The request body is over 64 MB. |
| 429 | The caller already has plans queued or running, and this one would take their unfinished forecasts past GET /dataset |
| 503 | A model worker or the subsurface grids aren't ready, or, with Redis, the Redis that keeps Idempotency-Key records isn't answering; retry shortly with the same key. |
Shared errors400401403500What they mean