Skip to content
Developers
Get an API token

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

GET/export-formats

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. Not cached: availability follows the plan and the worker.

Send a Novi API token as a bearer token on every request. Authentication
A plan

With plan, availability, reasons and defaults are that plan's.

  • Made without eur: true: the eur table and the presets that need it are unavailable, and monthly runs to the forecast's last month.
  • Made with bands: true: P10 and P90 are available for p_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=false drops the forecast table's EUR columns and makes the eur table and the presets that need EUR unavailable. eur_water=true adds water's EUR columns to eur and forecast.
  • The arps b_min and b_max defaults ignore a wells source's decline bounds, a well column holds the wells' labels, and p_levels is P50 alone.
  • Reasons say why in plain words; POST /exports' refusal also names the field to send.
  • Build columns from this answer: POST /exports refuses a column it doesn't list (409 for an oil or gas EUR column or eur_days without EUR, else 400, water's EUR columns without eur_water included).
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 until scenario picks 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

  • planstringOptional

    Format uuid

    A plan id from POST /plans: availability and defaults for that plan. Without it and without eur or eur_water, as for a plan with EUR.

  • eurbooleanOptional

    A wells source's source.eur: false describes wells forecast without EUR, and true or leaving it out, with EUR, though a POST /exports wells source that leaves source.eur out has EUR only when this server's forecast worker does, or when it sends eur_water or decline settings. Not with plan (400: the plan's own settings answer). Any other nonempty value is a 400.

  • eur_waterbooleanOptional

    A wells source's source.eur_water: true adds water's EUR columns and turns EUR on, as on a wells source, so eur=false beside it is a 400. Not with plan (400). Any other nonempty value is a 400.

  • scenariostringOptional

    1 to 60 characters

    With plan, on a plan made with scenarios: one scenario's name as POST /exports scenario takes it, exactly as the plan's scenarios list it, URL-encoded (660 ft is scenario=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 in details.scenarios. Without plan, a 400.

  • designsstringOptional

    With plan: design indexes from 0, comma-separated, as POST /exports designs takes 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. Without plan, a 400. It picks no scenario: with two or more, the presets that write Plan total rows, and combocurve, valnav and aries, stay unavailable without scenario.

  • includestringOptional

    Adds identity, table_rules, categories or groups to the answer, comma-separated or repeated, each once. Any other value is a 400 with details.field include.

    • identity: the fields POST /exports identity takes, each with its values or format, default and what it writes; with plan, unnamed_wells, how many wells well_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), and note, 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.
    • table_rules: each table's p_levels and fixed_columns, from the rules POST /exports refuses by. Build p_levels, reserves_categories and columns from 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 preset presets lists 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 without plan, eur or eur_water. A preset in no group is still a valid POST /exports preset.

    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_setstringOptional

    pattern ^[a-z0-9][a-z0-9-]{0,62}$

    The model set to answer from, an id from GET /model-sets. Absent: the set GET /model-sets names as default, the base dataset unless the server answers from a published set.

    • model_set=default reaches 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 once default is 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's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; naming resources of two sets in one request is a 400.

Responses

200 OK

Tables, presets and limits.

  • tablesarray of objectsRequired

    Tables.

    ShowHide 14 child fields in each item
    • idstringRequired

      Table id, as tables[].table takes it.

      "monthly""arps""eur""wells""designs""forecast""neighbors""calc_features""subsurface""combocurve_wells""shap""valnav_decline""combocurve_forecast""economics"
    • titlestringRequired

      Display name.

    • filestringRequired

      Its file in the zip.

    • descriptionstringRequired

      What it holds.

    • needs_eurbooleanRequired

      Whether it needs a plan made with eur: true.

    • availablebooleanRequired

      Whether it can be exported (from the named plan).

    • reasonstring or nullRequired

      Why not, when it can't.

    • columnsarray of objects or nullRequired

      Its 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
      • namestringRequired

        Column name.

      • unitstring or nullRequired

        Unit, as bbl or day.

      • descriptionstringRequired

        What it holds.

      • defaultbooleanRequired

        Written when the request names no columns.

      • streamstring or nullRequired

        The stream the column belongs to.

        "oil""gas""water"
    • optionsarray of objectsRequired

      Its options.

      ShowHide 8 child fields in each item
      • namestringRequired

        Option name in the table's request object.

      • titlestringRequired

        Display name.

      • typestringRequired

        Value type.

        "enum""enum[]""boolean""integer""number"
      • defaultnumber, string or boolean or array of stringsRequired

        Default, 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.

      • descriptionstringRequired

        What it does.

      • valuesarray of stringsOptional

        Allowed values (enum and enum[]).

      • minnumberOptional

        Lowest allowed.

      • maxnumberOptional

        Highest allowed.

    • rowsstringRequired

      What one row is.

    • parquetbooleanRequired

      Whether 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 nullOptional

      Only 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 stringsRequired

        1 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 stringsRequired

        The 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 nullRequired

        Why it writes none of the plan's other P-levels, when it doesn't: the plan was made without bands.

    • fixed_columnsbooleanOptional

      Only 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 stringsOptional

      Only 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 objectsRequired

    Presets.

    ShowHide 11 child fields in each item
    • idstringRequired

      Preset id, as preset takes it.

    • titlestringRequired

      Display name.

    • descriptionstringRequired

      What it holds.

    • tablesarray of objectsRequired

      Its 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.

        • tableanyRequired

          Always "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.

        • horizonstringOptional

          eur: 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 stringsOptional

          1 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"
        • totalsbooleanOptional

          Add Plan total rows per design and month at the end. Default true when the export has more than one well.

        • columnsarray of stringsOptional

          1 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.

        • tableanyRequired

          Always "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.

        • rampbooleanOptional

          Start with a linear ramp to the peak rate within the first 90 days. Default false.

        • reconcilestringOptional

          forward (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 decline b_min (a wells source's source.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 decline b_max (a wells source's source.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_unitsstringOptional

          The 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 stringsOptional

          1 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.

        • tableanyRequired

          Always "shap"

          SHAP values: each forecast's feature contributions by stream and ip day, a row per feature. At most 500 forecasts an export.

        • ip_daysstringOptional

          all (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 stringsOptional

          1 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.

        • tableanyRequired

          Always "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.

        • rampbooleanOptional

          Start 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.

        • tableanyRequired

          Always "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.

        • rampbooleanOptional

          Start 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.

        • tablestringRequired

          A 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 stringsOptional

          1 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.

        • tableanyRequired

          Always "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 economics echoes the deck and conventions and counts wells, priced and unpriced by reason, over every design and scenario.
        • flowsstringOptional

          Default "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"
    • availablebooleanRequired

      Whether it can be exported (from the named plan).

    • reasonstring or nullRequired

      Why not, when it can't.

    • media_typestringRequired

      The 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.

    • contentsstringRequired

      What 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"
    • plannedbooleanOptional

      Present, 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 stringsOptional

      Only 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"
    • notestringOptional

      Only with include=identity, and only when the preset has one: one sentence to show beside the preset, such as a file to load first.

  • parquetobjectRequired

    Parquet availability.

    ShowHide 3 child fields
    • availablebooleanRequired

      Whether Parquet is available.

    • load_kitsarray of stringsRequired

      The warehouses whose load scripts (load/<id>.sql) an export holds, in zip order, when it writes at least one Parquet table.

      "snowflake""databricks"
    • reasonstringOptional

      Why Parquet is unavailable.

  • default_presetstringRequired

    The preset an export without preset or tables runs.

  • p_levelsobjectRequired

    P-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 stringsRequired

      1 to 200 items

      The P-levels the plan has: P10 and P90 with bands, else P50.

      "P50""P10""P90"
    • defaultarray of stringsRequired

      1 to 200 items

      The P-levels an export writes without p_levels: P50.

      "P50""P10""P90"
    • reasonstring or nullRequired

      Why P10 and P90 aren't available, when they aren't.

    • conventionstringRequired

      Which band is the low one.

  • ariesobjectRequired

    ARIES export options.

    ShowHide 2 child fields
    • compatarray of stringsRequired

      The 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_compatstringRequired

      The compat mode an aries export without aries.compat writes.

      "fixed""fe"
  • limitsobjectRequired

    This server's retention and queue limits.

    ShowHide 8 child fields
    • ttl_hoursnumberRequired

      Hours a done export's file is kept.

    • max_bytesintegerRequired

      Bytes of done files kept; past it the oldest expire first.

    • max_queuedintegerRequired

      Exports queued or running at once per model set.

    • max_queued_per_planintegerRequired

      Exports queued or running at once per plan.

    • max_source_wellsintegerRequired

      Forecasts (wells × designs) a wells source may hold.

    • max_source_wells_by_designsarray of integersRequired

      Items ≥ 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.

    • evictionstringRequired

      Past max_bytes of finished files, which give up their files first: the oldest done exports; the newest is always kept.

      "oldest_first"
    • queue_countsstringRequired

      What max_queued and max_queued_per_plan count: exports queued or running.

      "queued_or_running"
  • callbacksobjectRequired

    Callbacks on this server.

    ShowHide 7 child fields
    • enabledbooleanRequired

      Whether callback_url is taken.

    • hostsarray of stringsRequired

      Hosts callbacks may go to; empty when off.

    • signedbooleanRequired

      Whether deliveries carry X-Export-Signature.

    • reasonstring or nullRequired

      Why callbacks are off, when they are.

    • eventsarray of stringsRequired

      The 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 nullRequired

      The header that carries the delivery's signature when signed is true; null when deliveries aren't signed. Header names are case-insensitive.

    • schemesarray of stringsRequired

      The 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 objectsOptional

    Only with include=categories: the presets by results category, in display order.

    ShowHide 3 child fields in each item
    • idstringRequired

      Category id.

      "production""eur""decline""handoff""spacing""drivers""value"
    • titlestringRequired

      Display name.

    • presetsarray of stringsRequired

      Its preset ids, as preset takes them, the one-click default first.

  • groupsarray of objectsOptional

    Only 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
    • idstringRequired

      Group id.

    • titlestringRequired

      Display name.

    • presetsarray of stringsRequired

      Its preset ids, as preset takes them, in display order.

  • identityobjectOptional

    Only with include=identity: the identity block POST /exports takes.

    ShowHide 2 child fields
    • fieldsarray of objectsRequired

      The fields POST /exports identity takes: well_id, start_date and reserves_category.

      ShowHide 7 child fields in each item
      • namestringRequired

        The field, as POST /exports identity takes it.

        "well_id""start_date""reserves_category"
      • defaultstringRequired

        What an export writes when the request leaves it out; with plan, for that plan: well_id is id on a Legacy Forecast.

      • descriptionstringRequired

        What it writes, and the preset option it sets.

      • valuesarray of stringsOptional

        The words it takes: well_id name, id or uid; start_date til.

      • formatstringOptional

        The date form it also takes (start_date).

        "YYYY-MM-DD"
      • typestringOptional

        Its 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

StatusWhen
404

No such well, grid, plan or route.

409

The request conflicts with the state of the plan or resource it names, and message says how: for example a plan still running or failed, a stale If-Match, an Idempotency-Key reused with another body, or a server without a state store.

Shared errors400401403500503What they mean