List export tables and presets
What an export can hold: tables (file, columns, options, rows), presets and the default one, P-levels, this server's retention and queue limits, and callbacks.
List export tables and presets
/export-formatsWhat an export can hold: tables (file, columns, options, rows), presets and the default one, P-levels, this server's retention and queue limits, and callbacks. Not cached: availability follows the plan and the worker.
A plan
With plan, availability, reasons and defaults are that plan's.
- Made without
eur: true: theeurtable and the presets that need it are unavailable, andmonthlyruns to the forecast's last month. - Made with
bands: true: P10 and P90 are available forp_levels. - Running or failed: every preset and table is unavailable, with the reason, as POST /exports answers 409.
A wells source
Without plan, eur and eur_water describe a POST /exports source.wells with those settings, as a plan made with them would be; without any of the three, as a plan with EUR.
eur=falsedrops theforecasttable's EUR columns and makes theeurtable and the presets that need EUR unavailable.eur_water=trueadds water's EUR columns toeurandforecast.- The
arpsb_min and b_max defaults ignore a wells source'sdeclinebounds, awellcolumn holds the wells' labels, andp_levelsis P50 alone. - Reasons say why in plain words; POST /exports' refusal also names the field to send.
- Build
columnsfrom this answer: POST /exports refuses a column it doesn't list (409 for an oil or gas EUR column oreur_dayswithout EUR, else 400, water's EUR columns withouteur_waterincluded).
An export's scope
With plan, scenario and designs scope an export as on POST /exports. Tables, columns, P-levels, defaults and limits stay the plan's.
- The drivers, valnav and combocurve presets count the scope: drivers its wells × designs, valnav and combocurve its designs and its wells' Well IDs. Their refusals then say "this export has", not "this plan has"; scenario reasons keep "this plan has".
- With two or more scenarios, the presets that write Plan total rows (
engineer,monthly,plan_tables) are unavailable untilscenariopicks one, since POST /exports refuses Plan total rows across scenarios (400). So are combocurve, valnav and aries, whose files carry no scenario.
The worker
The arps table and preset need the forecast worker's multi-segment Arps fit. The aries preset (no tables: an ARIES text file) needs a plan made with eur: true and a worker that writes ARIES and passed its startup check. Each gives the reason when unavailable.
Errors
With plan, a plan this server can't read yet answers 409, as POST /exports would: one running on another server, or one that failed before it was saved.
Tenant
With plan, a missing or other-tenant plan is a 404; without plan, no tenant is read.
Parameters
Query parameters
planstringOptionalFormat
uuidA plan id from POST /plans: availability and defaults for that plan. Without it and without
euroreur_water, as for a plan with EUR.eurbooleanOptionalA wells source's
source.eur:falsedescribes wells forecast without EUR, andtrueor leaving it out, with EUR, though a POST /exports wells source that leavessource.eurout has EUR only when this server's forecast worker does, or when it sendseur_wateror decline settings. Not withplan(400: the plan's own settings answer). Any other nonempty value is a 400.eur_waterbooleanOptionalA wells source's
source.eur_water:trueadds water's EUR columns and turns EUR on, as on a wells source, soeur=falsebeside it is a 400. Not withplan(400). Any other nonempty value is a 400.scenariostringOptional1 to 60 characters
With
plan, on a plan made with scenarios: one scenario's name as POST /exportsscenariotakes it, exactly as the plan'sscenarioslist it, URL-encoded (660 ftisscenario=660%20ft).The drivers, valnav and combocurve presets, and include=identity's
unnamed_wells, then count only its wells; the presets that write Plan total rows, and combocurve, valnav and aries, aren't refused for mixing scenarios. A name the plan lacks, or any name on a plan without scenarios, is a 400 on scenario with the plan's scenarios indetails.scenarios. Withoutplan, a 400.designsstringOptionalWith
plan: design indexes from 0, comma-separated, as POST /exportsdesignstakes them (designs=0,2). The drivers, valnav and combocurve presets then count only those designs.A repeated index counts once; one past the plan's designs is a 400 on designs with the plan's count in
details.designs. Withoutplan, a 400. It picks no scenario: with two or more, the presets that write Plan total rows, and combocurve, valnav and aries, stay unavailable withoutscenario.includestringOptionalAdds
identity,table_rules,categoriesorgroupsto the answer, comma-separated or repeated, each once. Any other value is a 400 with details.field include.identity: the fields POST /exportsidentitytakes, each with its values or format, default and what it writes; withplan,unnamed_wells, how many wellswell_id: "name"writes as their plan label (Plan well N): no name, or a name equal to that label.- Each preset gains
identity, the fields it reads (aries and combocurve: well_id and start_date; valnav: all three; a planned preset: those it will read; else empty), andnote, a sentence to show beside it, if it has one. - Each table gains
identity, the fields POST /exports takes with it (valnav_decline: all three; combocurve_wells and combocurve_forecast: well_id and start_date; else empty), even when a preset writing it is unavailable.
- Each preset gains
table_rules: each table'sp_levelsandfixed_columns, from the rules POST /exports refuses by. Buildp_levels,reserves_categoriesandcolumnsfrom them.categories: the presets by results category, in display order, with id, title and preset ids. A category's one-click download is its first presetpresetslists as available (for the plan, when sent); the rest are its menu.groups: the presets to offer a person choosing an export, by group, in display order, with id, title and preset ids, the same with or withoutplan,euroreur_water. A preset in no group is still a valid POST /exportspreset.
Availability and reasons stay on
presets."identity""table_rules""categories""groups""identity,table_rules""identity,categories""identity,groups""table_rules,identity""table_rules,categories""table_rules,groups""categories,identity""categories,table_rules""categories,groups""groups,identity""groups,table_rules""groups,categories""identity,table_rules,categories""identity,table_rules,groups""identity,categories,table_rules""identity,categories,groups"44 more values
"identity,groups,table_rules""identity,groups,categories""table_rules,identity,categories""table_rules,identity,groups""table_rules,categories,identity""table_rules,categories,groups""table_rules,groups,identity""table_rules,groups,categories""categories,identity,table_rules""categories,identity,groups""categories,table_rules,identity""categories,table_rules,groups""categories,groups,identity""categories,groups,table_rules""groups,identity,table_rules""groups,identity,categories""groups,table_rules,identity""groups,table_rules,categories""groups,categories,identity""groups,categories,table_rules""identity,table_rules,categories,groups""identity,table_rules,groups,categories""identity,categories,table_rules,groups""identity,categories,groups,table_rules""identity,groups,table_rules,categories""identity,groups,categories,table_rules""table_rules,identity,categories,groups""table_rules,identity,groups,categories""table_rules,categories,identity,groups""table_rules,categories,groups,identity""table_rules,groups,identity,categories""table_rules,groups,categories,identity""categories,identity,table_rules,groups""categories,identity,groups,table_rules""categories,table_rules,identity,groups""categories,table_rules,groups,identity""categories,groups,identity,table_rules""categories,groups,table_rules,identity""groups,identity,table_rules,categories""groups,identity,categories,table_rules""groups,table_rules,identity,categories""groups,table_rules,categories,identity""groups,categories,identity,table_rules""groups,categories,table_rules,identity"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
Tables, presets and limits.
tablesarray of objectsRequiredTables.
ShowHide 14 child fields in each item
idstringRequiredTable id, as tables[].table takes it.
"monthly""arps""eur""wells""designs""forecast""neighbors""calc_features""subsurface""combocurve_wells""shap""valnav_decline""combocurve_forecast""economics"titlestringRequiredDisplay name.
filestringRequiredIts file in the zip.
descriptionstringRequiredWhat it holds.
needs_eurbooleanRequiredWhether it needs a plan made with eur: true.
availablebooleanRequiredWhether it can be exported (from the named plan).
reasonstring or nullRequiredWhy not, when it can't.
columnsarray of objects or nullRequiredIts columns; null when it writes the plan's own (neighbors, calc features, subsurface), which can't be chosen.
ShowHide 5 child fields in each item
namestringRequiredColumn name.
unitstring or nullRequiredUnit, as bbl or day.
descriptionstringRequiredWhat it holds.
defaultbooleanRequiredWritten when the request names no columns.
streamstring or nullRequiredThe stream the column belongs to.
"oil""gas""water"
optionsarray of objectsRequiredIts options.
ShowHide 8 child fields in each item
namestringRequiredOption name in the table's request object.
titlestringRequiredDisplay name.
typestringRequiredValue type.
"enum""enum[]""boolean""integer""number"defaultnumber, string or boolean or array of stringsRequiredDefault, for this plan when one is named.
ShowHide 2 variants
Any of
number, string or boolean number, string or boolean or null
Values array of strings
Values.
descriptionstringRequiredWhat it does.
valuesarray of stringsOptionalAllowed values (enum and enum[]).
minnumberOptionalLowest allowed.
maxnumberOptionalHighest allowed.
rowsstringRequiredWhat one row is.
parquetbooleanRequiredWhether an export also writes this table as Parquet, parquet/<id>.parquet with an export_id column, when parquet.available and the request doesn't send parquet: false. A table without it is CSV only.
p_levelsobject or nullOptionalOnly with include=table_rules: the P-levels this table writes. Null when it writes no P-level rows: p_levels leaves it as it is, and p_levels with no table but these (and no preset aries) is a 400.
ShowHide 3 child fields
availablearray of stringsRequired1 to 200 items
The P-levels it writes when p_levels sends them: P50, plus P10 and P90 on a plan made with bands for monthly, eur, arps and combocurve_forecast; P50 alone for valnav_decline.
"P50""P10""P90"with_reserves_categoriesarray of stringsRequiredThe P-levels it writes only when reserves_categories names a category for each, every level its own: P10 and P90 for valnav_decline on a plan made with bands, else empty. Sent without one, they are a 400.
"P10""P90"reasonstring or nullRequiredWhy it writes none of the plan's other P-levels, when it doesn't: the plan was made without bands.
fixed_columnsbooleanOptionalOnly with include=table_rules: true when the table always writes its listed columns, so columns on it is a 400 (valnav_decline, combocurve_wells and combocurve_forecast: their tool's layout; economics: its fixed rollup layout). False on every other table, those whose columns is null included.
identityarray of stringsOptionalOnly with include=identity: the POST /exports identity fields a tables request with this table may send; empty when it takes none. A request with several tables may send any field one of them lists.
"well_id""start_date""reserves_category"
presetsarray of objectsRequiredPresets.
ShowHide 11 child fields in each item
idstringRequiredPreset id, as preset takes it.
titlestringRequiredDisplay name.
descriptionstringRequiredWhat it holds.
tablesarray of objectsRequiredIts tables (for the named plan); empty when unavailable, and for aries, which writes a text file.
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"
availablebooleanRequiredWhether it can be exported (from the named plan).
reasonstring or nullRequiredWhy not, when it can't.
media_typestringRequiredThe Content-Type of its download, GET /exports/{id}/file. application/zip: the preset's files with manifest.json and README.txt; for aries, its text file.
contentsstringRequiredWhat the download holds beside manifest.json and README.txt. tables: a CSV per entry in tables. text: one text file (aries: the ARIES import file, named after the plan), so no columns, streams or Parquet to choose.
With Parquet, tables also holds parquet/ files for the tables with parquet, and the load/ scripts (load/README.txt and a SQL file per parquet.load_kits entry).
"tables""text"plannedbooleanOptionalPresent, and true, only on a format listed ahead of its build: it can't be requested yet, so available is false, reason says "Coming soon" and an export with it answers 400.
identityarray of stringsOptionalOnly with include=identity: the POST /exports identity fields this preset reads; empty when it reads none. A planned preset lists the fields it will read.
"well_id""start_date""reserves_category"notestringOptionalOnly with include=identity, and only when the preset has one: one sentence to show beside the preset, such as a file to load first.
parquetobjectRequiredParquet availability.
ShowHide 3 child fields
availablebooleanRequiredWhether Parquet is available.
load_kitsarray of stringsRequiredThe warehouses whose load scripts (load/<id>.sql) an export holds, in zip order, when it writes at least one Parquet table.
"snowflake""databricks"reasonstringOptionalWhy Parquet is unavailable.
default_presetstringRequiredThe preset an export without preset or tables runs.
p_levelsobjectRequiredP-levels. 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).
ShowHide 4 child fields
availablearray of stringsRequired1 to 200 items
The P-levels the plan has: P10 and P90 with bands, else P50.
"P50""P10""P90"defaultarray of stringsRequired1 to 200 items
The P-levels an export writes without p_levels: P50.
"P50""P10""P90"reasonstring or nullRequiredWhy P10 and P90 aren't available, when they aren't.
conventionstringRequiredWhich band is the low one.
ariesobjectRequiredARIES export options.
ShowHide 2 child fields
compatarray of stringsRequiredThe values the aries preset takes in aries.compat: fixed repairs only what Novi's earlier Forecast Engine writes malformed; fe writes its bytes, defects included, and fails where its writer fails.
"fixed""fe"default_compatstringRequiredThe compat mode an aries export without aries.compat writes.
"fixed""fe"
limitsobjectRequiredThis server's retention and queue limits.
ShowHide 8 child fields
ttl_hoursnumberRequiredHours a done export's file is kept.
max_bytesintegerRequiredBytes of done files kept; past it the oldest expire first.
max_queuedintegerRequiredExports queued or running at once per model set.
max_queued_per_planintegerRequiredExports queued or running at once per plan.
max_source_wellsintegerRequiredForecasts (wells × designs) a wells source may hold.
max_source_wells_by_designsarray of integersRequiredItems ≥ 1
For 1 to 10 designs in order, the most wells a wells source may hold with that many designs: max_source_wells divided by the designs, rounded down, at least 1. The server refuses more with 400 on source.wells.
evictionstringRequiredPast max_bytes of finished files, which give up their files first: the oldest done exports; the newest is always kept.
"oldest_first"queue_countsstringRequiredWhat max_queued and max_queued_per_plan count: exports queued or running.
"queued_or_running"
callbacksobjectRequiredCallbacks on this server.
ShowHide 7 child fields
enabledbooleanRequiredWhether callback_url is taken.
hostsarray of stringsRequiredHosts callbacks may go to; empty when off.
signedbooleanRequiredWhether deliveries carry X-Export-Signature.
reasonstring or nullRequiredWhy callbacks are off, when they are.
eventsarray of stringsRequiredThe event a callback_url can be POSTed, sent as the body's type and the X-Export-Event header; POST /export-callbacks/test sends export.test.
"export.done""export.failed"signature_headerstring or nullRequiredThe header that carries the delivery's signature when signed is true; null when deliveries aren't signed. Header names are case-insensitive.
schemesarray of stringsRequiredThe URL schemes callback_url and POST /export-callbacks/test take. A server that allows private receivers (tests, a LAN) also takes http, though this list still says https.
categoriesarray of objectsOptionalOnly with include=categories: the presets by results category, in display order.
ShowHide 3 child fields in each item
idstringRequiredCategory id.
"production""eur""decline""handoff""spacing""drivers""value"titlestringRequiredDisplay name.
presetsarray of stringsRequiredIts preset ids, as preset takes them, the one-click default first.
groupsarray of objectsOptionalOnly with include=groups: the presets to offer a person choosing an export, by group, in display order. A preset in no group is still a valid preset. Availability and reasons stay on presets.
ShowHide 3 child fields in each item
idstringRequiredGroup id.
titlestringRequiredDisplay name.
presetsarray of stringsRequiredIts preset ids, as preset takes them, in display order.
identityobjectOptionalOnly with include=identity: the identity block POST /exports takes.
ShowHide 2 child fields
fieldsarray of objectsRequiredThe fields POST /exports identity takes: well_id, start_date and reserves_category.
ShowHide 7 child fields in each item
namestringRequiredThe field, as POST /exports identity takes it.
"well_id""start_date""reserves_category"defaultstringRequiredWhat an export writes when the request leaves it out; with plan, for that plan: well_id is id on a Legacy Forecast.
descriptionstringRequiredWhat it writes, and the preset option it sets.
valuesarray of stringsOptionalThe words it takes: well_id name, id or uid; start_date til.
formatstringOptionalThe date form it also takes (start_date).
"YYYY-MM-DD"typestringOptionalIts type, for free text (reserves_category).
"string"max_lengthintegerOptional≥ 1
The most characters it takes.
unnamed_wellsintegerOptional≥ 0
Only with plan: how many of its wells well_id name writes as their plan label (Plan well N): no name, or a name equal to that label; with scenario, only that scenario's wells.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
| 409 | The request conflicts with the state of the plan or resource it names, and |
Shared errors400401403500503What they mean