Price a whole plan in the background
Prices every well of a done plan under one design (and, on a scenario plan, one scenario) in the background, as POST /economics prices a plan well: one call for thousands of wells, and no client sums.
Price a whole plan in the background
/plans/{id}/economicsPrices every well of a done plan under one design (and, on a scenario plan, one scenario) in the background, as POST /economics prices a plan well: one call for thousands of wells, and no client sums.
The job
It answers 202 with a PlanEconomicsJob and its Location; GET /plans/{id}/economics/{job_id}?wait=25 until status is done or error. Jobs belong to the request tenant. An Idempotency-Key replays the first job for the same plan and body.
Totals
totals and each group sum their priced wells' monthly cash flows as if every well came online together, then take NPV, IRR and payback of that sum, so the pads' npv and capex add up to the totals'. An unpriced well counts in wells, not priced; the first (by plan index) names the reason. A group's economics are null only when none of its wells is priced (POST /economics instead gives a scenario with any unpriced well none).
Groups
No group is folded.
group_by: ["pad"]: pad keys in plan order of each pad's first well, wells without a pad last askey: null. A plan whose wells name no pad is a 400: send wells[].pad on POST /plans.group_by: ["formation"]: GET /formations order, wells without one last.include: ["wells"]adds a row per well in plan order;"breakeven", each group's and the totals' flat oil and gas breakeven prices, as POST /economics finds them.
Limits
At most 4 jobs run at once per tenant, across model sets and server tasks; the next is a 409 with Retry-After: 1. A job still pricing 10 minutes after it was posted, its wait for a server included, fails (unavailable): price one scenario or fewer groups. One no server took fails a minute later. Jobs are kept an hour after they finish, in Redis (shared by every server task) or the server's memory; with Redis, a job whose server stops runs again on another.
Errors
The plan's 409s come first (running, failed, or made without eur: true), then design, scenario, group_by, include, conventions, deck_id and deck, in that order; design, scenario, conventions and the deck are checked as POST /economics checks them.
Parameters
Path parameters
idstringRequiredFormat
uuidPlan id from POST /plans.
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
What to price, and how to group it.
designintegerOptionalDefault
0≥ 0, ≤ 9The plan design priced, its index from 0.
scenariostringOptional1 to 60 characters
On a plan made with scenarios, the one to price: required there (a 400 lists them), and a 400 on a plan without scenarios. A job prices one development; price each scenario in its own job.
deck_idstringOptionalThe deck to price with, one GET /economics/decks lists for the set; left out, the set's default deck (prototype-midland-flat; illustrative-haynesville-gas on a Haynesville set).
"prototype-midland-flat""house-70-3""illustrative-haynesville-gas"deckobjectOptionalOverrides of the deck's values for this request (every deck takes the same ranges); any left out keep the deck's.
ShowHide 20 child fields
oil_pricenumberOptional≥ 0, ≤ 300
$/bbl; 75 in the illustrative Midland deck.
oil_differentialnumberOptional≥ -50, ≤ 50
$/bbl; 4 in the illustrative Midland deck.
gas_pricenumberOptional≥ 0, ≤ 50
$/mcf; 3.5 in the illustrative Midland deck.
gas_differentialnumberOptional≥ -10, ≤ 10
$/mcf; 1 in the illustrative Midland deck.
ngl_pricenumberOptional≥ 0, ≤ 200
$/bbl; 26 in the illustrative Midland deck.
ngl_yield_bbl_per_mmcfnumberOptional≥ 0, ≤ 300
bbl/MMcf; 130 in the illustrative Midland deck.
shrinknumberOptional≥ 0, ≤ 1
fraction; 0.8 in the illustrative Midland deck.
opex_oilnumberOptional≥ 0, ≤ 100
$/bbl; 5.5 in the illustrative Midland deck.
opex_gasnumberOptional≥ 0, ≤ 20
$/mcf; 0.5 in the illustrative Midland deck.
opex_waternumberOptional≥ 0, ≤ 20
$/bbl; 0.6 in the illustrative Midland deck.
royaltynumberOptional≥ 0, ≤ 0.5
fraction; 0.25 in the illustrative Midland deck.
severance_oilnumberOptional≥ 0, ≤ 0.5
fraction; 0.046 in the illustrative Midland deck.
Show all 20 fields
severance_gasnumberOptional≥ 0, ≤ 0.5
fraction; 0.075 in the illustrative Midland deck.
ad_valoremnumberOptional≥ 0, ≤ 0.2
fraction; 0.025 in the illustrative Midland deck.
capex_per_wellnumberOptional≥ 0, ≤ 50000000
$; 2500000 in the illustrative Midland deck.
capex_drilling_per_ftnumberOptional≥ 0, ≤ 2000
$/ft; 150 in the illustrative Midland deck.
capex_stimulation_per_ftnumberOptional≥ 0, ≤ 2000
$/ft; 125 in the illustrative Midland deck.
capex_proppant_per_lbnumberOptional≥ 0, ≤ 2
$/lb; 0.08 in the illustrative Midland deck.
capex_fluid_per_bblnumberOptional≥ 0, ≤ 50
$/bbl; 3 in the illustrative Midland deck.
discount_ratenumberOptional≥ 0, ≤ 1
fraction per year; 0.25 in the illustrative Midland deck.
conventionsstringOptionalDefault
"prototype"How NPV and payback are counted: prototype, yearly discounting (the app's default), or fe, monthly discounting, which matches Novi's earlier Forecast Engine.
"prototype""fe"group_byarray of stringsOptionalunique items
Groups to sum, each once. Absent: totals only.
"pad""formation"includearray of stringsOptionalunique items
Optional parts, each once.
"wells""breakeven"
Responses
202 Accepted
The job, running (or, replaying an Idempotency-Key, as it is now).
idstringRequiredFormat
uuidJob id.
plan_idstringRequiredFormat
uuidThe plan priced.
statusstringRequiredrunning, then done or error.
"running""done""error"created_atstringRequiredFormat
date-timeWhen it was requested.
finished_atstring or nullRequiredFormat
date-timeWhen it finished or failed.
secondsnumberRequiredRun time so far, or in total once finished.
resultobject or nullRequiredOnce done, the plan priced; null otherwise.
ShowHide 8 child fields
plan_idstringRequiredFormat
uuidThe plan.
designintegerRequired≥ 0
The design priced.
scenariostring or nullRequiredThe scenario priced; null on a plan without scenarios.
deckobjectRequiredThe effective deck.
ShowHide 6 child fields
deck_idstringRequiredThe deck's id.
versionintegerRequired≥ 1
Its version.
namestringRequiredIts display name, as GET /economics/decks lists it; name results by it.
overridesarray of stringsRequiredThe fields this request overrode.
"oil_price""oil_differential""gas_price""gas_differential""ngl_price""ngl_yield_bbl_per_mmcf""shrink""opex_oil""opex_gas""opex_water""royalty""severance_oil""severance_gas""ad_valorem""capex_per_well""capex_drilling_per_ft""capex_stimulation_per_ft""capex_proppant_per_lb""capex_fluid_per_bbl""discount_rate"discount_ratenumberRequiredThe effective annual discount rate used for npv.
valuesobjectRequiredThe values priced with.
ShowHide 20 child fields
oil_pricenumberRequired$/bbl
oil_differentialnumberRequired$/bbl
gas_pricenumberRequired$/mcf
gas_differentialnumberRequired$/mcf
ngl_pricenumberRequired$/bbl
ngl_yield_bbl_per_mmcfnumberRequiredbbl/MMcf
shrinknumberRequiredfraction
opex_oilnumberRequired$/bbl
opex_gasnumberRequired$/mcf
opex_waternumberRequired$/bbl
royaltynumberRequiredfraction
severance_oilnumberRequiredfraction
Show all 20 fields
severance_gasnumberRequiredfraction
ad_valoremnumberRequiredfraction
capex_per_wellnumberRequired$
capex_drilling_per_ftnumberRequired$/ft
capex_stimulation_per_ftnumberRequired$/ft
capex_proppant_per_lbnumberRequired$/lb
capex_fluid_per_bblnumberRequired$/bbl
discount_ratenumberRequiredfraction per year
conventionsstringRequiredThe conventions priced under.
"prototype""fe"totalsobjectRequiredThe priced wells of a plan, a pad or a landing zone, summed month by month as if all came online together.
ShowHide 10 child fields
wellsintegerRequired≥ 0
Wells in it.
pricedintegerRequired≥ 0
Wells with a cash flow, summed.
capexnumber or nullRequiredCapex of the priced wells, $, all at month 0; null when none is priced.
npvnumber or nullRequiredNPV of the summed cash flow, $, at the deck discount_rate, as conventions says; null when none is priced.
irr_pctnumber or nullRequiredIRR of the summed cash flow, % a year; null when it never returns its capex or none is priced.
payback_monthsnumber or nullRequiredPayback of the summed cash flow, months; null when it never pays back or none is priced.
reasonstring or nullRequiredThe first unpriced well (by plan index) and why, as POST /economics names it; null when every well is priced.
keystring or nullOptionalOn a group: the pad key or formation; null for the wells without one. Absent on totals.
namestringOptionalOn a pad group, the pad's name when the plan gives one in
pads[].name; absent otherwise, and on totals and formation groups.keystays the pad key.breakevenobject or nullOptionalWith include breakeven: the flat oil and gas prices at which npv is 0, over the priced wells; null when none is priced.
ShowHide 3 child fields
oil_pricenumber or nullRequiredWTI, $/bbl: the flat oil price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between oil_price's min and max (GET /economics/deck).
gas_pricenumber or nullRequiredHenry Hub, $/mcf: the flat gas price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between gas_price's min and max.
discount_ratenumberRequiredThe effective annual discount rate npv was taken at, as deck.discount_rate.
groupsobjectOptionalWith group_by: the groups asked for.
ShowHide 2 child fields
padarray of objectsOptionalWith group_by pad: each pad key in plan order of its first well, no pad last; never folded.
Same fields as EconomicsRollup.
formationarray of objectsOptionalWith group_by formation: each formation in GET /formations order, none last.
Same fields as EconomicsRollup.
wellsarray of objectsOptionalWith include wells: every well priced, in plan order.
ShowHide 10 child fields in each item
indexintegerRequired≥ 0
The well's plan index.
labelstringRequiredThe well's name, else Plan well N.
padstring or nullRequiredIts pad key; null without one.
formationstring or nullRequiredIts target formation; null without one.
capexnumber or nullRequiredCapex, $; null when unpriced.
npvnumber or nullRequiredNPV, $; null when unpriced.
irr_pctnumber or nullRequiredIRR, % a year; null when unpriced or it never returns its capex.
payback_monthsnumber or nullRequiredPayback, months; null when unpriced or it never pays back.
reasonstring or nullRequiredWhy it has no cash flow, or null.
pad_namestringOptionalThe pad's name when the plan gives one in
pads[].name; absent otherwise.padstays the key.
errorobject or nullRequiredOnce failed, why; null otherwise.
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.
linksobjectRequiredRelated URLs.
ShowHide 1 child field
selfstringRequiredThis job.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | The plan is running, failed or was made without |
| 413 | The request body is over 10 MB. |
Shared errors400401403500503What they mean