List exports
Exports held in the request's model set (see model_set), newest first: queued, running, done, and tombstones of failed, cancelled and expired ones until the server's job cap drops them.
List exports
/exportsExports held in the request's model set (see model_set), newest first: queued, running, done, and tombstones of failed, cancelled and expired ones until the server's job cap drops them.
Filters
ids lists only those exports (the app lists the ones its browser created); plan and status filter.
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
idsstringOptionalOnly these exports: up to 100 export ids, comma-separated. Unknown ids are left out.
planstringOptionalFormat
uuidOnly exports of this plan id; a comparison export is listed under either side's plan.
statusstringOptionalOnly exports in this status.
"queued""running""done""error""cancelled""expired"limitintegerOptionalDefault
20≥ 1, ≤ 100Page size.
cursorstringOptionalPage to read:
next_cursorfrom the previous page.model_setstringOptionalpattern ^[a-z0-9][a-z0-9-]{0,62}$
The model set to answer from, an
idfrom GET /model-sets. Absent: the set GET /model-sets names asdefault, the base dataset unless the server answers from a published set.model_set=defaultreaches the base dataset; once the server retires it, a 400 naming the set answering instead.- An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in
details.allowed(published sets only oncedefaultis retired); a set that can't load, a 503 with the reason. - Plans and exports stay in their set: a call naming them (by path,
plan,ids,source.plan, a scenario'splan.id, or a comparison'sa.planandb.plan, also undersource.comparison) reaches it withoutmodel_set. - An explicit
model_setwins; naming resources of two sets in one request is a 400.
Responses
200 OK
Exports.
exportsarray of objectsRequiredExports, newest first.
ShowHide 27 child fields in each item
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.
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 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.
next_cursorstring or nullRequiredCursor for the next page.
Errors
Shared errors400401403500503What they mean