Skip to content
Developers
Get an API token

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

GET/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.

Send a Novi API token as a bearer token on every request. Authentication
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

  • idsstringOptional

    Only these exports: up to 100 export ids, comma-separated. Unknown ids are left out.

  • planstringOptional

    Format uuid

    Only exports of this plan id; a comparison export is listed under either side's plan.

  • statusstringOptional

    Only exports in this status.

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

    Default 20≥ 1, ≤ 100

    Page size.

  • cursorstringOptional

    Page to read: next_cursor from the previous page.

  • 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

Exports.

  • exportsarray of objectsRequired

    Exports, newest first.

    ShowHide 27 child fields in each item
    • 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.

  • next_cursorstring or nullRequired

    Cursor for the next page.

Errors

Shared errors400401403500503What they mean