Start an export
Queues an export of a done plan's tables as one zip and answers 202 with the export and its Location.
Start an export
/exportsQueues an export of a done plan's tables as one zip and answers 202 with the export and its Location. GET /exports/{id}?wait=25 until status is done (each answer waits for the status to change), then download file.url.
What you send
source names a done plan (source.plan), wells to forecast first (source.wells) or a comparison (source.comparison).
preset(from GET /export-formats) ortableswith their options: one or neither (the plan's default preset), not both.wellsanddesigns(indexes into the plan) andstreamsnarrow every table.- On a plan (or source wells) made with scenarios,
scenarioexports one scenario's wells; wells.csv and Parquetwellsthen add ascenariocolumn, last, whatever columns are chosen. - On a plan made with
bands: true,p_levelswith P10 and P90 adds their rows after each P50 in the monthly, eur and arps tables (P10 is the low curve), andband_eur: trueruns each band to its own EUR. Default P50 alone.
What you get
One CSV per table and, by default, Parquet for fixed-schema tables with Snowflake and Databricks load scripts. The worker fits an arps table first (progress.step arps); the fits stay with the plan for the next export with the same Arps settings.
Reuse and retries
The same request for the same plan returns the existing export with reused: true: 202 while it is queued or running, 200 once it is done.
An Idempotency-Key retry returns the first request's export as its response did (reused only if that had it), even once it failed, was cancelled or expired: it never starts a second one.
Queue and files
Small exports (up to 200,000 estimated rows by default) start at once, two at a time; larger ones run one at a time in order, with their queue_position.
- Each model set holds up to 20 exports queued or running, and 3 per plan; 409 past either. GET /export-formats
limitshas this server's. - An export keeps its plan from this call until its file is written, so deleting the plan or its eviction doesn't stop it.
- Files are kept 24 hours by default, and the oldest go first past the server's byte budget; the export then reads
expired. - With a state store, any server task answers GET (with
wait), the download and DELETE for another task's export, and the list for the model set named (sendmodel_setfor a set other than the default). - With the keys in Redis, an
Idempotency-Keyretry on another task replays the first export. An export whose task stopped before it finished readserror.
Errors
409 for a table that needs EUR on a plan made without eur: true; 503 for an arps table the worker can't fit.
- 400: wells that span scenarios with Plan total rows (
forecast, ormonthlywithtotals); it says to sendscenario, or to leave forecast out and set monthly totals false (a preset: onlyscenario). - 400: wells that span scenarios in ComboCurve, Val Nav or ARIES files, which carry no scenario; it says to send
scenario.
ARIES
preset: "aries" writes one ARIES economics import file, <plan name>.txt (else aries.txt), in the layout Novi's earlier Forecast Engine writes. Each well name (or id) heads its wells, then a block per design and P-level: START (the well's TIL month, else the plan's start day), the first 12 monthly volumes, 12-month hyperbolic refits and the terminal decline to the scope's EUR years. The worker writes the blocks (progress.step writing), sorted by name, by code point.
- Options go in
aries. With compatfethe export fails where the earlier writer fails, and a plan, design or well name holding a lone surrogate (which UTF-8 can't encode) fails it with a 409 error naming it; compatfixedwrites U+FFFD there and sorts by the text it writes. - P-levels follow
p_levels: P50 unless asked, where the earlier layout writes every level present. - One set of EUR settings per job: a scope whose wells differ in any of them is a 400 naming
wells; a scope with its own writes those, not the plan's. - 400s: a well name with nothing visible once cleaned,
streamsnarrower than the plan's (all three, or those its set serves), andparquet: true: ARIES writes every stream, as one text file. - Needs a plan made with
eur: true(409 without); 503 when the worker can't write ARIES (its startup check failed). Unavailable on a set serving neither oil nor gas. - manifest.json
aries.notessays what was left out and why (a failed forecast, a block without the major stream), which wells share a header and which designs would share a qualifier. An export that leaves out everything fails (409 in its error).
ComboCurve
preset: "combocurve" writes combocurve_wells.csv, a well header file, and combocurve_forecast.csv, forecast parameters with a row per Arps segment; tables combocurve_wells and combocurve_forecast write them alone. Columns follow ComboCurve's import article and API documentation. Its segments (default 2) and ramp (default false) are the arps table's.
- After the fit, the rows follow the plan's EUR decline (
eur.arps: its hyperbolic, then the terminal decline), scaled so ComboCurve's daily sum of the curve's rows totals the plan's EUR, so the rate steps at the last IP day (manifest.jsoncombocurve.curve). - The tail starts from the fit's cumulative at that day, so its gap to the plan's EUR curve past it follows the fit's own miss there.
- ComboCurve sums each day's start rate where Novi integrates, so its daily sums read slightly above Novi's volumes;
tool_euris that sum. - Di Eff-Sec is secant effective, in percent per 365.25-day year, and each segment runs from its Start Date to its End Date inclusive, the next starting the day after.
- P-levels are series named by exceedance, as ComboCurve names them: Novi's P10 (low) as P90, Novi's P90 (high) as P10, P50 as best. Each is that level's own Arps fit and, with
band_eur, EUR decline, with its owneur_check.csvrows. - 400s naming the fix:
identity.reserves_category(ComboCurve's files carry none),columnson either table, avalnav_declinetable beside either (each writes its owneur_check.csv: make two exports), andcombocurvewith other presets or tables. - manifest.json
combocurve.formula_keyscounts the IDs starting with=,+,-or@:wellsin the well header,curvesin the forecast file. A Well Name or Target Formation starting with=,+,-,@, a tab or a carriage return gets a leading'.
ComboCurve's two passes
ComboCurve keys forecast parameters on INPT ID, which it creates with each well. Load combocurve_wells.csv as a well header import, add the wells to a forecast, and export the project's well list (Chosen ID, INPT ID). Then send the same request with combocurve: {"inpt_ids": {"<Well ID>": "<INPT ID>"}} and import that export's combocurve_forecast.csv. Without the map, INPT ID holds the Well ID, and manifest.json combocurve.inpt_ids counts the wells without one.
SHAP
The shap table writes each P50 forecast's SHAP values, a row per well, design, stream, ip day and feature; shap_value and expected_value are unrounded, in the stream's unit (bbl for oil and water, mcf for gas). Formation's one-hot columns are summed into novi_formation, and zero contributions are left out. p_levels adds nothing to it.
- The worker explains every forecast first (
progress.stepexplain), two at a time, so a call on the same model waits behind at most two. A plan well already explained by GET .../explanations is reused; the export keeps nothing on the plan. ip_daysall(default) orlast;top(1 to 50) keeps each row group's largest features and sums the rest into(other), as GET .../explanations'topdoes.- A forecast or stream without an explanation gets an error row, counted in manifest.json
shap; an export with none explained fails with code internal and details.worker forecast. - At most 500 forecasts (scoped wells × designs) per export, checked before it queues: past it, a 400 on the table's
tablewithdetails.maxanddetails.count; scope it withwellsordesigns.
Condensate
Where the model set labels its oil slot condensate (stream_labels, GET /model-sets), or a Legacy Forecast is of condensate, oil is condensate in every file under oil's names (oil_bbl, ComboCurve's oil, Val Nav's OIL); ARIES writes CND (B/M), aries.major_stream oil. Economics prices it at the oil price and differential. manifest.json source.stream_labels holds the labels and README.txt says oil = condensate; other exports have neither.
Wells instead of a plan
source.wells takes wells as POST /plans does, up to limits.max_source_wells forecasts (wells × designs), 500 by default; GET /export-formats limits reports this server's value and, in max_source_wells_by_designs, the most wells per design count. It forecasts them in a plan of its own (unlisted, 404 by id) while progress.step is forecast, then writes the zip.
- Labels and design names starting with
=,+,-,@, a tab or a carriage return get a leading'; a plan's design names are written as they are. - The same wells, labels, designs and settings return the existing export.
- Each model set forecasts up to 4 exports' wells at once, counting a cancelled export's until its forecast stops; 409 past it.
A comparison
source.comparison takes a POST /comparisons body without its pricing fields or wells (ExportComparisonSource) and writes that route's answer as tables, as Parquet too unless parquet: false. delta is b − a and delta_pct (b − a) / a × 100.
- comparison_totals.csv, a row per total: metric, unit, ip_day, horizon_years (on the rows
horizonadds), a, b, delta, delta_pct, a_wells, b_wells. - comparison_spread.csv, a row per side and statistic of the per-well distribution: metric, unit, ip_day, side (a, b, delta or delta_pct), statistic, value; delta rows cover mean and q50.
- With
group_by, comparison_groups.csv: group_by and group_key, then the spread's columns. - With
includecurves, comparison_curves.csv: side, stream, unit, ip_day, cum, rate, and p10 and p90 with bands. Withaligncalendar, comparison_calendar.csv: the same by month_start. - With
includewells, comparison_wells.csv, every pair by a_index: metric, unit, ip_day, a_index, b_index, label, b_label, a, b, delta, delta_pct, band_position. - manifest.json
comparisonholds each side as POST /comparisons echoes it and the warnings; with pairing, the pairs (method, a_only and b_only with counts), the per-well summary andincludeinputs' input changes. README.txt says it in words. - A text cell (a label, or a formation or scenario in group_key) starting with
=,+,-,@, a tab or a carriage return gets a leading'. - A side that is missing, running, failed or on another model set, and any other 400 the body gets, answers as POST /comparisons does,
fieldundersource.comparison. - The tables are fixed:
preset,tables,wells,designs,scenario,streams,p_levels,aries,flags,identityandsource.comparison.wellsare a 400, sent or null, as is asource.comparisonthat isn't an object. - The same comparison of the same plans (defaults filled in) returns the existing export. It counts against each side's plan's queue limit, and GET /exports?plan= lists it under either.
- Its
sourceiskind: comparison,plannull,comparisonnaming both sides. The file is comparison-export-<date>.zip unlessnameis sent.
A Legacy Forecast
source.plan takes a Legacy Forecast's id from GET /plans?origin=all, and the same writers write it: its curves and EUR are the run's, with Arps segments fitted here. manifest.json source adds origin and, on a condensate run, stream_labels.
streamsdefaults to the run'sstreams; a stream it didn't forecast is a 400 naming those it did.- The neighbors, calc_features, subsurface, shap and economics tables, and the plan_tables, drivers, economics and aries presets, are a 409 with
details.reasonfe_plan_unsupported. identity.well_iddefaults toid, the run's unique well key, the same in every export of the run, so same-named wells export; names stay in Well Name and eur_check.csv'swell. With"name", two wells of one name are a 400 naming both.- ComboCurve's files and the monthly cumulatives at each 30-day IP day for P50, P10 and P90 of a run with bands, in one call (monthly.csv's at month m is the run's at IP day 30 × m):
{"source": {"plan": "<id>"}, "tables": [{"table": "combocurve_wells"}, {"table": "combocurve_forecast"}, {"table": "monthly", "horizon": "forecast", "values": ["cumulative"], "totals": false}], "p_levels": ["P50", "P10", "P90"], "parquet": false}
Callbacks
With callback_url, the server POSTs {"type": "export.done" | "export.failed", "export": <the export, as GET /exports/{id} returns it, less callbacks>} once the export is done or fails (not when it is cancelled).
- Only to hosts the server allows (GET /export-formats
callbacks; else a 400 oncallback_url), at public https addresses. - Up to 5 URLs per export: the same request with another
callback_urladds it, and sends it at once when the export is already done. - 3 retries, after 2 s, 15 s and 60 s; each attempt, DNS lookup included, has 10 s. Any 2xx is delivered;
callbackson the export shows each delivery. - Verify
X-Export-Signaturewhencallbacks.signed:t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">with the server's shared secret. Refuse atmore than 5 minutes from your clock. - Dedupe on
X-Export-Delivery, one id per export and URL that every retry repeats;X-Export-IdandX-Export-Eventcome with it.
A receiver should answer 2xx quickly, then download the file from export.file.url: the payload never inlines it.
Tenant
Exports belong to the request's tenant: lists hold only its exports, and another tenant's export is a 404 to read, download or delete. A signed-in user's tenant is their customer; a configured user's, the server's default tenant.
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
The plan or wells, the preset or tables, and a callback URL.
sourceobjectRequiredWhat to export: a done plan, wells to forecast first, or a comparison of two plans.
ShowHide 3 variants
One of
ExportPlanSource object
A done plan.
planstringRequiredFormat
uuidA done plan's id, from POST /plans.
ExportWellsSource object
Wells the export forecasts first, in a plan of its own.
kindstringRequiredWhat the wells are, which names the file: drawn (drawn-well-…), pad (pad-…) or optimizer (optimizer-…).
"drawn""pad""optimizer"wellsarray of objectsRequired1 to 500 items
The wells; up to limits.max_source_wells forecasts (500 by default; GET /export-formats reports this server's) divided by the number of designs.
ShowHide 18 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].
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, as in POST /plans.
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
As in POST /plans: every well has one or none, at most 20; then the export's
scenariopicks one.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.
Show all 18 fields
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.
labelstring or nullOptionalup to 100 characters
The well's name in every table (the well column). Default Drawn well for one drawn well, else Well 1, Well 2, …; each well's must differ.
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.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.
til_datestringOptionalFormat
dateTIL date, YYYY-MM-DD, for every well no narrower layer dates, as POST /plans takes it.
pdpbooleanOptionalDefault
trueSpace against existing (PDP) wells. A scenario's
pdpinscenariosbeats it, and this stays the manifest'spdp.eurbooleanOptionalFit EUR for monthly volumes to EUR and the EUR summary. Default true when the server has EUR (GET /dataset eur.available; when the forecast worker doesn't answer within 1.5 s, its last ready answer, else a 503), or when decline is sent at any layer or eur_water is true; true answers 503 without it.
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. Witheurleft out it turns EUR on, asdeclinedoes; witheur: falseit is a 400 on source.eur_water.declineobjectOptionalDecline fit settings, as on POST /plans.
Same fields as DeclineSettings.
depletion_chainbooleanOptionalChain depletion in the export's plan, as POST /plans'
depletion_chaindoes: on by default where GET /datasetdepletion_chain.availableis true, else off, andfalseturns it off. The export'ssource.depletion_chainechoes it where the plan would.namestring or nullOptionalup to 100 characters
A name for the wells, as a plan name: the export's title when it has none.
ExportComparisonSource object
A comparison of two done plans or scenarios, written as its tables.
comparisonobjectRequiredTwo plan sides and what to measure, as POST /comparisons takes them, but without
wells(the download writes every pair, by a_index) or the pricing fieldsdeck_id,deck,conventionsandincludevalue: each is a 400 here, as is a forecast source side.ShowHide 10 child fields
aobjectRequiredSide a, the base:
deltais b − a anddelta_pctis relative to it.ShowHide 3 child fields
planstringRequiredFormat
uuidA done plan's id, as POST /plans returns it.
scenariostringOptional1 to 60 characters
On a plan made with scenarios, the scenario to compare, exactly as its
scenarioslist it; required there, and a 400 on a plan without scenarios. A name it doesn't have is a 400 whosedetails.scenarioslists them.designintegerOptionalDefault
0≥ 0The design, as its index in the plan's
designs; 0 by default. One past the last is a 400.
bobjectRequiredSide b. It may be the plan of side a, with another scenario or design.
Same fields as ComparisonSide.
metricstringOptionalThe per-well metric distribution, groups and curves measure: eur_boe by default when both sides have EUR, else cum_boe.
Per-well metrics:
eur_oil(bbl),eur_gas(mcf) andeur_boe(BOE) are each well's EUR and need a plan made witheur: true(400 otherwise);cum_oil,cum_gasandcum_boeare the forecast's cumulative volume atip_day. BOE is oil + gas / 6, only for wells with both."eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"ip_dayintegerOptional≥ 1
For a cum_ metric, the ip_day to measure, one of the forecast ip_days GET /dataset lists; 1080 by default. With an eur_ metric it is a 400.
normalize_lateral_ftnumberOptional≥ 100, ≤ 20000
Scale each well's value to this lateral length in distribution and groups, as GET /plans/{id}/stats does: value × normalize_lateral_ft / its lateral_length_ft. Totals and curves stay unscaled. 100 to 20,000.
group_bystringOptionalAlso compare each group of wells: design (every design index either side has), formation (each well's target formation, null for none), scenario (a 400 when neither side's plan has scenarios), or pad (the pad key, null for wells without one; 400 when neither plan has keys). Pads pair by key in side a plan order then new side b keys, null last, without a cap or Other row.
"design""formation""scenario""pad"includearray of stringsOptionalOptional parts. Any other value is a 400 listing these.
"curves""bands""wells""inputs"pairobjectOptionalHow to pair the sides' wells; adds pairs to the answer.
ShowHide 3 child fields
bystringOptionalDefault
"auto"auto (default): name when every well on both sides has a real name and none repeats on a side, else location; with a forecast source side, saved, else name, else uwi.
- name: names found once on each side; a repeated name's wells pair by location within it.
- location: heel and bottom hole each within tolerance_ft; same formation first, then closest, then nearest TVD; one to one.
- index: by position, with a warning.
- map: the pairs in map.
- uwi and saved: forecast source sides only; location and index: plan sides only.
"auto""name""location""index""map""uwi""saved"tolerance_ftnumberOptionalDefault
300≥ 1, ≤ 5280With auto or location: how far apart, ft, a pair's heels (else surface holes) and bottom holes may each be; 300 by default. With another by it is a 400.
maparray of arraysOptionalItems 2 items
With by map, and only then: the pairs, each well once; an index or Well ID outside its side's wells or used twice is a 400 naming the entry (pair.map[k]).
horizonstring or objectOptionalEach side's cumulative at a common horizon beside its EUR; needs EUR on both sides (a 400 naming the side without).
ShowHide 2 variants
Any of
own: each side's EUR only, the default string
own: each side's EUR only, the default.
"own"Option 2 object
A common horizon: cumulative rows at that many years.
yearsintegerRequired≥ 1, ≤ 50
Years.
alignstringOptionalcalendaradds curves.calendar, each side's curve by calendar month (needs include curves and a well with a TIL date on each side, or a start date on every well of a forecast source side); months_on, the default, adds nothing."months_on""calendar"
presetstringOptionalA preset id from GET /export-formats, as engineer. Not with tables.
tablesarray of objectsOptional1 to 14 items
The tables to write, each once, with their options. Not with preset.
ShowHide 7 variants in each item
One of
MonthlyTable object
The monthly table and its options.
tableanyRequiredAlways
"monthly"Monthly volumes: each well's forecast by 30-day month on production, and with horizon eur its EUR's decline to the EUR day.
horizonstringOptionaleur: to the EUR day (the plan's eur_years; needs a plan made with eur: true); forecast: the forecast's months. Defaults to eur on a plan with EUR, else forecast.
"eur""forecast"valuesarray of stringsOptional1 to 200 items
Columns per stream: the month's volume, the cumulative at its end, the average daily rate. Default volume and cumulative.
"volume""cumulative""rate"totalsbooleanOptionalAdd Plan total rows per design and month at the end. Default true when the export has more than one well.
columnsarray of stringsOptional1 to 200 items
Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.
ArpsTable object
The arps table and its options.
tableanyRequiredAlways
"arps"Arps parameters: each forecast curve's multi-segment Arps fit, a row per segment.
segmentsintegerOptional≥ 1, ≤ 4
Hyperbolic segments before the terminal exponential. Default 2.
rampbooleanOptionalStart with a linear ramp to the peak rate within the first 90 days. Default false.
reconcilestringOptionalforward (the default where this server's worker takes it, else independent): each later segment rescaled so its rate starts where the one before stops; independent: each segment fit on its own. GET /export-formats lists the methods this server's worker takes and the default.
"independent""forward"b_minnumberOptional≥ 0.5, ≤ 2.5
The lowest b the table's hyperbolics may take. Default: the plan's plan-wide
declineb_min (a wells source'ssource.decline) when the export sends neither bound, else 0.5, also when that b_min is below 0.5; a stream's or layer's bounds don't count.b_maxnumberOptional≥ 0.5, ≤ 2.5
The highest b the table's hyperbolics may take, above b_min. Default: the plan's plan-wide
declineb_max (a wells source'ssource.decline) when the export sends neither bound, else 2.5, also when that plan's b_min is below 0.5; a stream's or layer's bounds don't count.exponential_unitsstringOptionalThe exponential row's declines. annual (default): the terminal decline in d_tangent and d_secant and −ln(1 − terminal decline) in d_nominal, all per year; per_day: d_tangent per day and the others blank.
"annual""per_day"columnsarray of stringsOptional1 to 200 items
Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.
ShapTable object
The shap table and its options.
tableanyRequiredAlways
"shap"SHAP values: each forecast's feature contributions by stream and ip day, a row per feature. At most 500 forecasts an export.
ip_daysstringOptionalall (default): every forecast ip day; last: the last forecast ip day only.
"all""last"topinteger or nullOptional≥ 1, ≤ 50
The most features to keep per well, design, stream and ip day, by absolute contribution, the rest summed into one
(other)row; null (default) keeps every feature.columnsarray of stringsOptional1 to 200 items
Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.
ValNavTable object
The valnav_decline table and its options.
tableanyRequiredAlways
"valnav_decline"Val Nav decline: each curve's Arps fit through the last IP day, then rows that total the plan's EUR, as Val Nav's decline CSV, a row per segment. Needs a plan made with eur: true and the worker's Arps fit. Its 17 columns are Val Nav's: columns is a 400.
segmentsintegerOptional≥ 1, ≤ 2
Hyperbolic rows fitted to the forecast before its last IP day, 1 (default) or 2. With 1 the rows add one more hyperbolic from the last IP day to the terminal decline; with 2 the second runs on to the tail. Either way they total the plan's EUR; 3 or 4 is a 400, since Val Nav's templates take at most two hyperbolic rows before the tail.
rampbooleanOptionalStart with a linear ramp (N −1) to the peak rate within the first 90 days. Default false.
ComboCurveTable object
The combocurve_forecast table and its options.
tableanyRequiredAlways
"combocurve_forecast"ComboCurve forecast parameters: each curve's Arps fit to the forecast's last IP day, then the plan's EUR decline, as ComboCurve's forecast parameters import takes it, a row per segment. Needs a plan made with eur: true and the worker's Arps fit. Its 14 columns are ComboCurve's: columns is a 400.
segmentsintegerOptional≥ 1, ≤ 4
The fit's hyperbolic segments up to the forecast's last IP day, as the arps table's; then the plan's EUR decline: a hyperbolic row when its switch day is after that day, and its terminal decline. Default 2.
rampbooleanOptionalStart with a linear segment to the peak rate within the first 90 days, as the arps table's. Default false.
PlainTable object
A table without options.
tablestringRequiredA table without options: eur (needs a plan made with eur: true), wells, designs, forecast, neighbors, calc_features, subsurface or combocurve_wells, ComboCurve's well header, whose columns are ComboCurve's (columns is a 400).
"eur""wells""designs""forecast""neighbors""calc_features""subsurface""combocurve_wells"columnsarray of stringsOptional1 to 200 items
Only these columns, in the table's order; absent for its default columns. Not for neighbors, calc_features and subsurface, which write the plan's own columns.
EconomicsTable object
The economics table and its options.
tableanyRequiredAlways
"economics"Economics: economics.csv, unrounded NPV, capex, IRR and payback from the P50 forecasts of the streams the plan's model set serves, whatever streams, p_levels or flags say. Needs EUR.
- Rows: wells in plan order, then pads in first-well order (no pad last), then a plan row, per design and scenario in plan order. Pads and plan sum cash flows as if every well came online together.
- Fixed columns (columns is a 400); null numbers blank; CSV only.
- manifest.json
economicsechoes the deck and conventions and counts wells, priced and unpriced by reason, over every design and scenario.
flowsstringOptionalDefault
"none"none writes no cash flows; pads adds economics_flows.csv for pads and plan; wells adds every priced well too. Month 0 is capex; cash_flow_usd and cumulative_usd are unrounded, with row, well, design, scenario and pad identifying each series.
"none""pads""wells"
wellsarray of integers or nullOptional1 to 100000 itemsItems ≥ 0
Only these plan wells, by index in the plan (repeats count once); null or absent for all of them. Up to 10,000 indexes, or as many as the plan has wells when it has more.
designsarray of integers or nullOptional1 to 10000 itemsItems ≥ 0
Only these designs, by index in the plan (repeats count once); null or absent for all of them.
scenariostringOptional1 to 60 characters
Instead of wells: only this scenario's wells, of a plan (or source wells) made with scenarios; a 400 with wells, on a plan without scenarios, or naming none of its scenarios (details.scenarios lists them).
streamsarray of stringsOptional1 to 200 items
Only these streams' columns (default all three).
"oil""gas""water"namestring or nullOptionalup to 100 characters
Your name for the export; the zip's file name is this plus .zip.
callback_urlstring or nullOptionalup to 2048 characters
Where to POST the export once it is done or fails: https, to a host the server allows (GET /export-formats callbacks).
parquetbooleanOptionalDefault
trueAlso write fixed-schema tables as Parquet under parquet/, with export_id and Snowflake and Databricks load scripts. Tables whose GET /export-formats
parquetis false are CSV only. true with preset aries is a 400 (a text file).p_levelsarray of stringsOptional1 to 200 items
The P-levels the monthly, eur, arps, valnav_decline and combocurve_forecast tables write, a row each (P50, P10, P90), and the blocks preset aries writes. Default P50 alone, even on a plan with bands.
P10 and P90 need a plan made with bands: true (409 without); p_levels needs a table with P-levels or preset aries (400 without). combocurve_forecast writes each as a series: P50 as best, Novi's P10 (low) as P90, its P90 (high) as P10; combocurve_wells writes none. P10 is the low curve and P90 the high one, Novi's convention; SPE PRMS uses the reverse (its P90 is the low, proved case).
"P50""P10""P90"ariesobjectOptionalWith preset aries only (400 otherwise): its options, each with a default.
ShowHide 6 child fields
compatstringOptionalDefault
"fixed"fixed: the layout Novi's earlier Forecast Engine writes, repairing only what is malformed in that layout (duplicate or over-long qualifiers, nan and 100.0 declines, control characters, a failed refit window); fe: that layout byte for byte, defects included.
"fixed""fe"major_streamstringOptionalDefault
"oil"The stream each block writes first; a block without it is left out, with a note. The default is oil, or gas on a model set without oil; a stream the set doesn't serve is a 400, and on a set serving neither, ARIES is unavailable.
"oil""gas"well_keystringOptionalDefault
"name"What heads each well: its name, or its id (its key, as DRAWN-0). api is a 400: planned wells have no API numbers.
"name""api""id"start_datestring or nullOptionalDefault
nullFormatdateEvery well's START month, instead of its TIL date (the plan's start day without one); from 1900-01-01 to 2199-12-31.
cleanbooleanOptionalDefault
trueControl characters (C0, C1) and line separators in well, design and plan names become spaces. false writes them raw and needs compat fe: compat fixed always cleans (400).
last_windowstringOptionalDefault
"overlap"How a stream's last refit window is written when fewer than 12 months follow the last whole one: overlap (the default) writes 12 months that overlap the window before; remaining writes only the months left.
remaining uses the 12-month refit's b and the yearly decline at which those months carry the forecast's volume, and needs compat fixed (a 400 with fe). Where the refit fails, or no decline to 2 decimals carries that volume within 1% (a rising tail, say), it writes the months' mean as a flat line, and a negative mean ends the stream there. Resolved settings list it only when remaining.
"overlap""remaining"
Show all 17 fields
identityobjectOptionalWell ID, start date and reserves category for the economics presets; only a preset or table that reads a field takes it.
GET /export-formats?include=identity lists the fields of each preset (presets[].identity) and table (tables[].identity): valnav_decline reads all three, the combocurve tables well_id and start_date.
- With tables, a field none of them lists is a 400 naming it.
- With another preset, or tables none of which reads identity, it is a 400 naming the presets and tables that do; a planned preset first answers that it isn't available yet.
- Not an object, or an unknown field: a 400 listing the three.
- With preset aries it resolves into aries's options before the export is keyed, so a request with identity or with aries shares one export (the second answers reused: true); the job echoes aries alone.
- With valnav and combocurve it is resolved, defaults filled, so a request with or without the defaults shares one export; the job echoes it resolved.
ShowHide 3 child fields
well_idstringOptionalDefault
"name"Each well's Well ID: name (the default) writes its name, else its plan label (Plan well N); id its plan well id, as DRAWN-0; uid its
well_uidfrom GET /plans/{id}/curves.- On a Legacy Forecast the default is id, its unique well key: a run's well names can repeat.
- uid is 32 characters, the same on every read of the plan, so plans whose wells share names or ids get different Well IDs.
- With preset aries it is aries.well_key: send either, or the same value in both (null counts as not sent); different values are a 400 naming both.
- A 400 naming identity.well_id: id or uid on a plan well without an id, name on a well whose name has no visible character, uid with preset aries or on wells sent in
source(a new plan each export).
"name""id""uid"start_datestringOptionalDefault
"til"pattern ^(til|\d{4}-\d{2}-\d{2})$Each well's start date: til (the default) writes its TIL date, else the plan's day; a real day as YYYY-MM-DD, 1900-01-01 to 2199-12-31, sets that day for every well.
Anything else is a 400 naming identity.start_date. With preset aries it is aries.start_date (til as null or left out): send either, or the same value in both (null counts as not sent); different values are a 400 naming both.
reserves_categorystringOptionalDefault
"PUD"1 to 40 charactersThe reserves category written for every well, 1 to 40 characters with no control characters, PUD when left out. Only presets that write one read it: valnav writes it as Rescat (for P50; reserves_categories names P10's and P90's); ARIES and ComboCurve write none, so with preset aries or combocurve it is a 400.
reserves_categoriesobjectOptionalWith preset valnav or the valnav_decline table only (400 otherwise): the Rescat Val Nav's file writes per P-level; P50's replaces identity.reserves_category.
P10 and P90 each need their own when p_levels sends them (two on one category is a 400); a level not in p_levels is a 400 naming it. Novi never maps P-levels to 1P, 2P or 3P: its P10 is the low curve, PRMS's P90.
ShowHide 3 child fields
P50stringOptional1 to 40 characters
P50's reserves category: 1 to 40 characters with no control characters.
P10stringOptional1 to 40 characters
P10's reserves category: 1 to 40 characters with no control characters.
P90stringOptional1 to 40 characters
P90's reserves category: 1 to 40 characters with no control characters.
combocurveobjectOptionalWith preset combocurve or its tables only (400 otherwise): what ComboCurve's forecast parameters file keys each well on, for the second pass. Part of the export's key.
ShowHide 1 child field
inpt_idsobjectOptionalEach Well ID's INPT ID, from the ComboCurve project's well list once combocurve_wells.csv is loaded, keyed by the Well IDs (Chosen IDs) in this export. Wells left out keep their Well ID as INPT ID.
A 400 names the entry for an unknown key, a repeated value (compared as written, a lone surrogate as U+FFFD), a control character, or a left-out well's Well ID as value.
economicsobjectOptionalWith the economics table or preset only (else a 400 on economics). deck_id, deck and conventions as POST /economics takes them; left out, the plan model set's default deck and prototype conventions.
fe counts with monthly discounting and whole-month payback. The resolved deck and conventions, defaults included, are part of the export key.
ShowHide 3 child fields
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"
flagsbooleanOptionalDefault
falseWith
preset, or neither (the default preset): true addsflaggedandout_of_rangecolumns to the preset's eur, wells and forecast tables. Default false.flagged: whether a design's inputs (in wells, any exported design's) fall outside the model's training data.out_of_range: each such input with its value and range. GET /export-formats describes both.- They follow the other columns (on a plan's wells table, before its layer columns and
scenario), in CSV, and in Parquet for eur and wells; nothing else changes. - The export and manifest.json echo
flags: true; their eur, wells and forecast tables list the resolvedcolumns. - With
tables, true is a 400 (list both in each table'scolumns), as is a preset with none of those tables (aries).
- They follow the other columns (on a plan's wells table, before its layer columns and
Responses
The identical export, already done (reused: true).
idstringRequiredFormat
uuidExport id.
statusstringRequiredqueued, running, then done, error or cancelled; expired once a done export's file is removed.
"queued""running""done""error""cancelled""expired"created_atstringRequiredFormat
date-timeWhen it was requested.
started_atstring or nullRequiredFormat
date-timeWhen it started running.
finished_atstring or nullRequiredFormat
date-timeWhen it finished, failed or was cancelled.
secondsnumber or nullRequiredRun time so far, or in total once finished; null until it starts.
sourceobjectRequiredThe plan, wells or comparison exported.
ShowHide 7 child fields
kindstringRequiredplan, the kind a wells source named, or comparison.
"plan""drawn""pad""optimizer""comparison"planstring or nullRequiredFormat
uuidPlan id; null for a wells source, whose plan is the export's own, and for a comparison, whose plans are in comparison.
namestring or nullRequiredPlan name, or the wells source's; for a comparison, each side's plan name (and scenario) joined by vs.
wellsintegerRequiredWells in the plan; for a comparison, both sides' wells added.
designsintegerRequiredDesigns in the plan; for a comparison, 2, a design per side.
depletion_chainobjectOptionalA wells source's chain, where POST /plans would echo it for the same request: what it read and did, as GET /plans/{id} shows it. Never on a plan source.
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.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
comparisonobjectOptionalOnly on a comparison export: its two sides.
ShowHide 2 child fields
aobjectRequiredOne side of a comparison export, its defaults filled in.
ShowHide 3 child fields
planstringRequiredFormat
uuidThe side's plan id.
scenariostring or nullRequiredThe side's scenario; null for a plan without scenarios.
designintegerRequired≥ 0
The design, as its index in
designs.
bobjectRequiredOne side of a comparison export, its defaults filled in.
Same fields as ExportComparisonSide.
namestring or nullRequiredThe export's name, as requested.
presetstring or nullRequiredThe preset it ran, or null for tables.
tablesarray of objectsRequiredThe tables written, with every option resolved.
Same fields as ExportTable.
wellsarray of integers or nullRequiredThe plan wells (or source wells) exported, or null for all.
designsarray of integers or nullRequiredThe designs exported, or null for all.
Show all 27 fields
streamsarray of stringsRequired1 to 200 items
The streams exported.
"oil""gas""water"parquetbooleanRequiredWhether this export includes Parquet and load scripts.
queue_positioninteger or nullRequired≥ 1
While queued, its place in its lane's queue from 1; else null.
progressobjectRequiredProgress.
ShowHide 5 child fields
stepstringRequiredqueued, then forecast, arps, explain, economics or writing while running (writing covers an aries export's worker calls), then done.
"queued""forecast""arps""explain""economics""writing""done"fractionnumberRequired≥ 0, ≤ 1
Share of the step's work done; writing starts again near 0 after the steps before it reach 1.
- arps reaches 1 when its fits finish, explain when every forecast is explained, economics when every design and scenario is priced.
- writing: CSV rows written, or with Parquet tables 0.9 for the CSV rows and the rest as Parquet files go into the zip; with preset aries, the worker's slices to 0.9, then the file. Below 1 until the export is done.
rowsintegerRequiredRows written so far.
rows_totalintegerRequiredRows the export writes, as estimated at the start.
bytesintegerRequiredBytes written so far.
fileobject or nullRequiredOnce done, the zip; null otherwise.
ShowHide 6 child fields
namestringRequiredThe zip's file name.
bytesintegerRequiredSize.
sha256stringRequiredpattern ^[0-9a-f]{64}$
SHA-256 of the zip, hex.
urlstringRequiredIts download URL (GET /exports/{id}/file).
expires_atstringRequiredFormat
date-timeWhen the file is removed.
entriesarray of objectsRequiredThe CSV and Parquet table files in the zip; load/ scripts, manifest.json and README.txt are also included.
ShowHide 3 child fields in each item
namestringRequiredCSV or parquet/ file in the zip.
rowsintegerRequiredData rows.
bytesintegerRequiredUncompressed size.
errorobject or nullRequiredWhy the export failed; a wells source's forecast errors name their field under source.
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.
callbacksarray of objectsRequiredup to 5 items
Its callback URLs and their deliveries.
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.
linksobjectRequiredRelated URLs.
ShowHide 2 child fields
selfstringRequiredThis export.
filestringRequiredIts zip.
reusedbooleanOptionalPOST /exports only: true when this is an identical export the server already had.
p_levelsarray of stringsOptional1 to 200 items
The P-levels written, when they are more than P50.
"P50""P10""P90"ariesobjectOptionalFor preset aries: its options, resolved.
ShowHide 6 child fields
compatstringRequiredDefault
"fixed"fixed: the layout Novi's earlier Forecast Engine writes, repairing only what is malformed in that layout (duplicate or over-long qualifiers, nan and 100.0 declines, control characters, a failed refit window); fe: that layout byte for byte, defects included.
"fixed""fe"major_streamstringRequiredDefault
"oil"The stream each block writes first; a block without it is left out, with a note. The default is oil, or gas on a model set without oil; a stream the set doesn't serve is a 400, and on a set serving neither, ARIES is unavailable.
"oil""gas"well_keystringRequiredDefault
"name"What heads each well: its name, or its id (its key, as DRAWN-0). api is a 400: planned wells have no API numbers.
"name""api""id"start_datestring or nullRequiredDefault
nullFormatdateEvery well's START month, instead of its TIL date (the plan's start day without one); from 1900-01-01 to 2199-12-31.
cleanbooleanRequiredDefault
trueControl characters (C0, C1) and line separators in well, design and plan names become spaces. false writes them raw and needs compat fe: compat fixed always cleans (400).
last_windowstringOptionalDefault
"overlap"How a stream's last refit window is written when fewer than 12 months follow the last whole one: overlap (the default) writes 12 months that overlap the window before; remaining writes only the months left.
remaining uses the 12-month refit's b and the yearly decline at which those months carry the forecast's volume, and needs compat fixed (a 400 with fe). Where the refit fails, or no decline to 2 decimals carries that volume within 1% (a rising tail, say), it writes the months' mean as a flat line, and a negative mean ends the stream there. Resolved settings list it only when remaining.
"overlap""remaining"
identityobjectOptionalWith preset valnav or combocurve, or their tables: the identity the files were written with, every field they read resolved, so requests sent with or without the defaults echo alike; reserves_category with Val Nav only.
ShowHide 3 child fields
well_idstringRequiredname, id or uid, as identity.well_id resolved (when left out, name; on a Legacy Forecast, id).
"name""id""uid"start_datestringRequiredtil, or the date identity.start_date sent, as YYYY-MM-DD.
reserves_categorystringOptionalWith Val Nav only, since ComboCurve's files carry none: P50's Rescat: reserves_categories' P50 entry when sent, else identity.reserves_category, else PUD.
reserves_categoriesobjectOptionalOnly when the request sent reserves_categories for P10 or P90: their Rescat, as sent. A P50 entry becomes identity.reserves_category, echoed there.
ShowHide 3 child fields
P50stringOptional1 to 40 characters
P50's reserves category: 1 to 40 characters with no control characters.
P10stringOptional1 to 40 characters
P10's reserves category: 1 to 40 characters with no control characters.
P90stringOptional1 to 40 characters
P90's reserves category: 1 to 40 characters with no control characters.
combocurveobjectOptionalOnly when the request sent combocurve.inpt_ids with an entry.
ShowHide 1 child field
inpt_idsintegerRequired≥ 1
How many INPT IDs the request sent, not the IDs.
flagsbooleanOptionalOnly when the request sent
flags: true: the preset's eur, wells and forecast tables listflaggedandout_of_rangeincolumns. To repeat the export, send the samepresetwithflags: true.
The export, queued or running (or the identical one already queued or running, with reused: true; or, replaying an Idempotency-Key, as it is now).
idstringRequiredFormat
uuidExport id.
statusstringRequiredqueued, running, then done, error or cancelled; expired once a done export's file is removed.
"queued""running""done""error""cancelled""expired"created_atstringRequiredFormat
date-timeWhen it was requested.
started_atstring or nullRequiredFormat
date-timeWhen it started running.
finished_atstring or nullRequiredFormat
date-timeWhen it finished, failed or was cancelled.
secondsnumber or nullRequiredRun time so far, or in total once finished; null until it starts.
sourceobjectRequiredThe plan, wells or comparison exported.
ShowHide 7 child fields
kindstringRequiredplan, the kind a wells source named, or comparison.
"plan""drawn""pad""optimizer""comparison"planstring or nullRequiredFormat
uuidPlan id; null for a wells source, whose plan is the export's own, and for a comparison, whose plans are in comparison.
namestring or nullRequiredPlan name, or the wells source's; for a comparison, each side's plan name (and scenario) joined by vs.
wellsintegerRequiredWells in the plan; for a comparison, both sides' wells added.
designsintegerRequiredDesigns in the plan; for a comparison, 2, a design per side.
depletion_chainobjectOptionalA wells source's chain, where POST /plans would echo it for the same request: what it read and did, as GET /plans/{id} shows it. Never on a plan source.
Same fields as DepletionChainEcho.
comparisonobjectOptionalOnly on a comparison export: its two sides.
ShowHide 2 child fields
aobjectRequiredOne side of a comparison export, its defaults filled in.
Same fields as ExportComparisonSide.
bobjectRequiredOne side of a comparison export, its defaults filled in.
Same fields as ExportComparisonSide.
namestring or nullRequiredThe export's name, as requested.
presetstring or nullRequiredThe preset it ran, or null for tables.
tablesarray of objectsRequiredThe tables written, with every option resolved.
Same fields as ExportTable.
wellsarray of integers or nullRequiredThe plan wells (or source wells) exported, or null for all.
designsarray of integers or nullRequiredThe designs exported, or null for all.
Show all 27 fields
streamsarray of stringsRequired1 to 200 items
The streams exported.
"oil""gas""water"parquetbooleanRequiredWhether this export includes Parquet and load scripts.
queue_positioninteger or nullRequired≥ 1
While queued, its place in its lane's queue from 1; else null.
progressobjectRequiredProgress.
ShowHide 5 child fields
stepstringRequiredqueued, then forecast, arps, explain, economics or writing while running (writing covers an aries export's worker calls), then done.
"queued""forecast""arps""explain""economics""writing""done"fractionnumberRequired≥ 0, ≤ 1
Share of the step's work done; writing starts again near 0 after the steps before it reach 1.
- arps reaches 1 when its fits finish, explain when every forecast is explained, economics when every design and scenario is priced.
- writing: CSV rows written, or with Parquet tables 0.9 for the CSV rows and the rest as Parquet files go into the zip; with preset aries, the worker's slices to 0.9, then the file. Below 1 until the export is done.
rowsintegerRequiredRows written so far.
rows_totalintegerRequiredRows the export writes, as estimated at the start.
bytesintegerRequiredBytes written so far.
fileobject or nullRequiredOnce done, the zip; null otherwise.
ShowHide 6 child fields
namestringRequiredThe zip's file name.
bytesintegerRequiredSize.
sha256stringRequiredpattern ^[0-9a-f]{64}$
SHA-256 of the zip, hex.
urlstringRequiredIts download URL (GET /exports/{id}/file).
expires_atstringRequiredFormat
date-timeWhen the file is removed.
entriesarray of objectsRequiredThe CSV and Parquet table files in the zip; load/ scripts, manifest.json and README.txt are also included.
ShowHide 3 child fields in each item
namestringRequiredCSV or parquet/ file in the zip.
rowsintegerRequiredData rows.
bytesintegerRequiredUncompressed size.
errorobject or nullRequiredWhy the export failed; a wells source's forecast errors name their field under source.
Same fields as ErrorBody.
callbacksarray of objectsRequiredup to 5 items
Its callback URLs and their deliveries.
Same fields as ExportCallback.
linksobjectRequiredRelated URLs.
ShowHide 2 child fields
selfstringRequiredThis export.
filestringRequiredIts zip.
reusedbooleanOptionalPOST /exports only: true when this is an identical export the server already had.
p_levelsarray of stringsOptional1 to 200 items
The P-levels written, when they are more than P50.
"P50""P10""P90"ariesobjectOptionalFor preset aries: its options, resolved.
Same fields as AriesSettings.
identityobjectOptionalWith preset valnav or combocurve, or their tables: the identity the files were written with, every field they read resolved, so requests sent with or without the defaults echo alike; reserves_category with Val Nav only.
ShowHide 3 child fields
well_idstringRequiredname, id or uid, as identity.well_id resolved (when left out, name; on a Legacy Forecast, id).
"name""id""uid"start_datestringRequiredtil, or the date identity.start_date sent, as YYYY-MM-DD.
reserves_categorystringOptionalWith Val Nav only, since ComboCurve's files carry none: P50's Rescat: reserves_categories' P50 entry when sent, else identity.reserves_category, else PUD.
reserves_categoriesobjectOptionalOnly when the request sent reserves_categories for P10 or P90: their Rescat, as sent. A P50 entry becomes identity.reserves_category, echoed there.
ShowHide 3 child fields
P50stringOptional1 to 40 characters
P50's reserves category: 1 to 40 characters with no control characters.
P10stringOptional1 to 40 characters
P10's reserves category: 1 to 40 characters with no control characters.
P90stringOptional1 to 40 characters
P90's reserves category: 1 to 40 characters with no control characters.
combocurveobjectOptionalOnly when the request sent combocurve.inpt_ids with an entry.
ShowHide 1 child field
inpt_idsintegerRequired≥ 1
How many INPT IDs the request sent, not the IDs.
flagsbooleanOptionalOnly when the request sent
flags: true: the preset's eur, wells and forecast tables listflaggedandout_of_rangeincolumns. To repeat the export, send the samepresetwithflags: true.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | A conflict with the plan, the queue, the callbacks or the Idempotency-Key.
|
| 413 | The request body is over 10 MB. |
| 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