Skip to content
Developers
Get an API token

Get an export

Status, queue position, progress (step, fraction, rows and bytes written) and, once done, the file: name, size, SHA-256, URL, expiry and each entry's rows and bytes.

Get an export

GET/exports/{id}

Status, queue position, progress (step, fraction, rows and bytes written) and, once done, the file: name, size, SHA-256, URL, expiry and each entry's rows and bytes.

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

Queued or running, it answers with Retry-After: 1; send wait instead of polling.

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

Path parameters

Query parameters

  • waitintegerOptional

    ≥ 1, ≤ 25

    Use this instead of polling: on a queued or running export, the answer is held until its status changes (queued to running, or to done, error or cancelled), or this many seconds pass.

    Whole seconds, 1 to 25 (400 otherwise). The answer is what a GET without wait would get when the wait ends, Retry-After included; a finished job answers at once. A client that disconnects ends the wait.

  • 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

The export.

  • idstringRequired

    Format uuid

    Export id.

  • statusstringRequired

    queued, running, then done, error or cancelled; expired once a done export's file is removed.

    "queued""running""done""error""cancelled""expired"
  • created_atstringRequired

    Format date-time

    When it was requested.

  • started_atstring or nullRequired

    Format date-time

    When it started running.

  • finished_atstring or nullRequired

    Format date-time

    When it finished, failed or was cancelled.

  • secondsnumber or nullRequired

    Run time so far, or in total once finished; null until it starts.

  • sourceobjectRequired

    The plan, wells or comparison exported.

    ShowHide 7 child fields
    • kindstringRequired

      plan, the kind a wells source named, or comparison.

      "plan""drawn""pad""optimizer""comparison"
    • planstring or nullRequired

      Format uuid

      Plan id; null for a wells source, whose plan is the export's own, and for a comparison, whose plans are in comparison.

    • namestring or nullRequired

      Plan name, or the wells source's; for a comparison, each side's plan name (and scenario) joined by vs.

    • wellsintegerRequired

      Wells in the plan; for a comparison, both sides' wells added.

    • designsintegerRequired

      Designs in the plan; for a comparison, 2, a design per side.

    • depletion_chainobjectOptional

      A 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
      • appliedbooleanRequired

        Whether the chain ran: false when no served model reads neighbors' production, and the plan then ran as without it.

      • reasonstring or nullRequired

        Why the chain didn't run; null when it did.

      • featuresarray of stringsRequired

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

        Where existing (PDP) parents' production came from: history is their production to the dataset's as_of, held flat after; extended continues it with Novi's production forecast for each existing well past its history.

        "history""extended"
      • extensionobject or nullRequired

        The 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. With per_well these are the plan's, and a parent with its own settings was extended with those: read each well's inputs.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.

        • oilobjectOptional

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

        • gasobjectOptional

          With per-stream settings, the settings gas was fit with.

          Same fields as StreamDecline.

        • waterobjectOptional

          Only with eur_water: true: the settings water was fit with. Its presence is the echo of the flag.

          Same fields as StreamDecline.

        • per_wellbooleanOptional

          Only when a well has its own settings: these are the request's or plan's, not every well's; inputs.resolved.decline gives each well's.

          true
    • comparisonobjectOptional

      Only on a comparison export: its two sides.

      ShowHide 2 child fields
      • aobjectRequired

        One side of a comparison export, its defaults filled in.

        ShowHide 3 child fields
        • planstringRequired

          Format uuid

          The side's plan id.

        • scenariostring or nullRequired

          The side's scenario; null for a plan without scenarios.

        • designintegerRequired

          ≥ 0

          The design, as its index in designs.

      • bobjectRequired

        One side of a comparison export, its defaults filled in.

        Same fields as ExportComparisonSide.

  • namestring or nullRequired

    The export's name, as requested.

  • presetstring or nullRequired

    The preset it ran, or null for tables.

  • tablesarray of objectsRequired

    The tables written, with every option resolved.

    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"
  • wellsarray of integers or nullRequired

    The plan wells (or source wells) exported, or null for all.

  • designsarray of integers or nullRequired

    The designs exported, or null for all.

Show all 27 fields
  • streamsarray of stringsRequired

    1 to 200 items

    The streams exported.

    "oil""gas""water"
  • parquetbooleanRequired

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

  • progressobjectRequired

    Progress.

    ShowHide 5 child fields
    • stepstringRequired

      queued, 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.
    • rowsintegerRequired

      Rows written so far.

    • rows_totalintegerRequired

      Rows the export writes, as estimated at the start.

    • bytesintegerRequired

      Bytes written so far.

  • fileobject or nullRequired

    Once done, the zip; null otherwise.

    ShowHide 6 child fields
    • namestringRequired

      The zip's file name.

    • bytesintegerRequired

      Size.

    • sha256stringRequired

      pattern ^[0-9a-f]{64}$

      SHA-256 of the zip, hex.

    • urlstringRequired

      Its download URL (GET /exports/{id}/file).

    • expires_atstringRequired

      Format date-time

      When the file is removed.

    • entriesarray of objectsRequired

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

        CSV or parquet/ file in the zip.

      • rowsintegerRequired

        Data rows.

      • bytesintegerRequired

        Uncompressed size.

  • errorobject or nullRequired

    Why the export failed; a wells source's forecast errors name their field under source.

    ShowHide 3 child fields
    • codestringRequired

      Machine-readable code.

      "invalid_argument""not_found""conflict""unavailable""internal"
    • messagestringRequired

      What went wrong and how to fix it.

    • detailsobjectRequired

      Context: field names the input at fault, as wells[3].tvd_ft.

      ShowHide 1 child field
      • fieldstringOptional

        The input at fault.

  • callbacksarray of objectsRequired

    up to 5 items

    Its callback URLs and their deliveries.

    ShowHide 6 child fields in each item
    • urlstringRequired

      Where it goes: its origin, with /… for any path or query. The server keeps the whole URL, for delivery only.

    • statusstringRequired

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

      The receiver's last HTTP status.

    • last_errorstring or nullRequired

      Why the last attempt failed.

    • delivered_atstring or nullRequired

      Format date-time

      When a 2xx came back.

  • linksobjectRequired

    Related URLs.

    ShowHide 2 child fields
    • selfstringRequired

      This export.

    • filestringRequired

      Its zip.

  • reusedbooleanOptional

    POST /exports only: true when this is an identical export the server already had.

  • p_levelsarray of stringsOptional

    1 to 200 items

    The P-levels written, when they are more than P50.

    "P50""P10""P90"
  • ariesobjectOptional

    For preset aries: its options, resolved.

    ShowHide 6 child fields
    • compatstringRequired

      Default "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_streamstringRequired

      Default "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_keystringRequired

      Default "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 nullRequired

      Default nullFormat date

      Every well's START month, instead of its TIL date (the plan's start day without one); from 1900-01-01 to 2199-12-31.

    • cleanbooleanRequired

      Default true

      Control 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_windowstringOptional

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

    With 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_idstringRequired

      name, id or uid, as identity.well_id resolved (when left out, name; on a Legacy Forecast, id).

      "name""id""uid"
    • start_datestringRequired

      til, or the date identity.start_date sent, as YYYY-MM-DD.

    • reserves_categorystringOptional

      With 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_categoriesobjectOptional

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

      1 to 40 characters

      P50's reserves category: 1 to 40 characters with no control characters.

    • P10stringOptional

      1 to 40 characters

      P10's reserves category: 1 to 40 characters with no control characters.

    • P90stringOptional

      1 to 40 characters

      P90's reserves category: 1 to 40 characters with no control characters.

  • combocurveobjectOptional

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

  • flagsbooleanOptional

    Only when the request sent flags: true: the preset's eur, wells and forecast tables list flagged and out_of_range in columns. To repeat the export, send the same preset with flags: true.

Errors

StatusWhen
404

No such well, grid, plan or route.

Shared errors400401403500503What they mean