Skip to content
Developers
Get an API token

Start an export

Queues an export of a done plan's tables as one zip and answers 202 with the export and its Location.

Start an export

POST/exports

Queues an export of a done plan's tables as one zip and answers 202 with the export and its Location. GET /exports/{id}?wait=25 until status is done (each answer waits for the status to change), then download file.url.

Send a Novi API token as a bearer token on every request. Authentication
What you send

source names a done plan (source.plan), wells to forecast first (source.wells) or a comparison (source.comparison).

  • preset (from GET /export-formats) or tables with their options: one or neither (the plan's default preset), not both.
  • wells and designs (indexes into the plan) and streams narrow every table.
  • On a plan (or source wells) made with scenarios, scenario exports one scenario's wells; wells.csv and Parquet wells then add a scenario column, last, whatever columns are chosen.
  • On a plan made with bands: true, p_levels with P10 and P90 adds their rows after each P50 in the monthly, eur and arps tables (P10 is the low curve), and band_eur: true runs each band to its own EUR. Default P50 alone.
What you get

One CSV per table and, by default, Parquet for fixed-schema tables with Snowflake and Databricks load scripts. The worker fits an arps table first (progress.step arps); the fits stay with the plan for the next export with the same Arps settings.

Reuse and retries

The same request for the same plan returns the existing export with reused: true: 202 while it is queued or running, 200 once it is done.

An Idempotency-Key retry returns the first request's export as its response did (reused only if that had it), even once it failed, was cancelled or expired: it never starts a second one.

Queue and files

Small exports (up to 200,000 estimated rows by default) start at once, two at a time; larger ones run one at a time in order, with their queue_position.

  • Each model set holds up to 20 exports queued or running, and 3 per plan; 409 past either. GET /export-formats limits has this server's.
  • An export keeps its plan from this call until its file is written, so deleting the plan or its eviction doesn't stop it.
  • Files are kept 24 hours by default, and the oldest go first past the server's byte budget; the export then reads expired.
  • With a state store, any server task answers GET (with wait), the download and DELETE for another task's export, and the list for the model set named (send model_set for a set other than the default).
  • With the keys in Redis, an Idempotency-Key retry on another task replays the first export. An export whose task stopped before it finished reads error.
Errors

409 for a table that needs EUR on a plan made without eur: true; 503 for an arps table the worker can't fit.

  • 400: wells that span scenarios with Plan total rows (forecast, or monthly with totals); it says to send scenario, or to leave forecast out and set monthly totals false (a preset: only scenario).
  • 400: wells that span scenarios in ComboCurve, Val Nav or ARIES files, which carry no scenario; it says to send scenario.
ARIES

preset: "aries" writes one ARIES economics import file, <plan name>.txt (else aries.txt), in the layout Novi's earlier Forecast Engine writes. Each well name (or id) heads its wells, then a block per design and P-level: START (the well's TIL month, else the plan's start day), the first 12 monthly volumes, 12-month hyperbolic refits and the terminal decline to the scope's EUR years. The worker writes the blocks (progress.step writing), sorted by name, by code point.

  • Options go in aries. With compat fe the export fails where the earlier writer fails, and a plan, design or well name holding a lone surrogate (which UTF-8 can't encode) fails it with a 409 error naming it; compat fixed writes U+FFFD there and sorts by the text it writes.
  • P-levels follow p_levels: P50 unless asked, where the earlier layout writes every level present.
  • One set of EUR settings per job: a scope whose wells differ in any of them is a 400 naming wells; a scope with its own writes those, not the plan's.
  • 400s: a well name with nothing visible once cleaned, streams narrower than the plan's (all three, or those its set serves), and parquet: true: ARIES writes every stream, as one text file.
  • Needs a plan made with eur: true (409 without); 503 when the worker can't write ARIES (its startup check failed). Unavailable on a set serving neither oil nor gas.
  • manifest.json aries.notes says what was left out and why (a failed forecast, a block without the major stream), which wells share a header and which designs would share a qualifier. An export that leaves out everything fails (409 in its error).
Val Nav and ComboCurve

Each curve's rows keep its Arps fit through the forecast's last IP day, then follow the plan's EUR decline, so the curve totals the plan's EUR in the tool, with eur_check.csv, manifest.json and README.txt beside. The worker fits each curve first (progress.step arps) with reconcile forward and the plan's b bounds, kept with the plan as an arps table's fits are. GET /export-formats describes every column; manifest.json keys here sit under valnav or combocurve.

  • Needs a plan made with EUR (409) and the worker's Arps fit with reconcile forward (503; GET /export-formats then lists the preset and fitted table unavailable, with that reason). combocurve_wells alone needs neither.
  • One design per fitted file (a 400 naming designs), and one well per Well ID: two wells with one Well ID, or a Well ID with no visible character, are a 400 naming them.
  • GET /export-formats?plan lists the preset unavailable for a plan with more than one design or two wells of one Well ID under the default identity, and the tables available: designs and wells scope them.
  • identity sets the Well ID (well_id: the well's name, else its plan label, its id, or its well_uid, which keeps two plans' same-named wells apart) and the start date (til, or one date).
  • Well IDs and Rescat are written raw: control characters as spaces, CSV quoting.
  • A curve without a plan EUR (P10 and P90 without band_eur, water without eur_water), whose EUR has no decline fit, or that no Val Nav template brings to it keeps its fit, its reason in eur_check.csv note and manifest.json kept_as_fitted.
  • eur_check.csv has each curve's plan EUR, Arps EUR and the tool's EUR of its rows (tool_eur), then max_cum_gap_pct and max_cum_gap_month: over the model's months, the signed largest gap of the rows' cumulative to the forecast's at day 30 × m, and that m.
    • The rows' cumulative is as Val Nav reads them; for ComboCurve, integrated as arps_eur, not ComboCurve's daily sum.
    • m runs from 1 to the last IP day / 30, rounded down, within the rows. Months where the forecast's cumulative is 0 or missing are left out; both are blank when none is left. manifest.json eur_check.streams has each stream's largest.
Val Nav

preset: "valnav", or tables: [{"table": "valnav_decline"}], writes valnav_decline.csv in the layout Val Nav exports (no public Val Nav import specification exists). Load it into a Val Nav database in imperial units, then compare each curve's EUR with eur_check.csv. It has no unit row: rates per day (bbl/d, Mcf/d raw gas), declines nominal in percent per 365.2425-day year.

  • After the fit, the rows follow Novi's EUR decline from the fit's rate on the last IP day: one hyperbolic at its b down to the terminal decline, then the tail. With segments 2 the second fitted hyperbolic runs on to the tail, at the decline that totals the EUR.
  • eur_check.csv template and manifest.json valnav.templates name each curve's layout: TwoSegmentHyperbolic (one hyperbolic and the tail), SingleSegment (one switching on or after the EUR day), ThreeSegment (two hyperbolics), and TwoSegmentWithRampUp or ThreeSegmentWithRampUp with a ramp.
  • manifest.json valnav.warnings: tail_below_terminal, where the fit's last-IP-day rate is too low for the terminal decline and every later decline is scaled down by one factor; tail_bend, a cumulative more than 10% from the plan's EUR decline at year 5, 10, 20 or 30.
  • It also warns of a ramp with no tail (no template names one) and counts UWIs and Rescats starting with =, +, - or @. A curve without a fit is left out, in valnav.skipped.
  • eur_check.csv adds tool_vs_forecast_pct and tail_bend_pct.
  • Rescat is identity.reserves_category (PUD by default). P50 alone by default: P10 and P90 need reserves_categories with a category for each level sent, every level its own (400 otherwise).
ComboCurve

preset: "combocurve" writes combocurve_wells.csv, a well header file, and combocurve_forecast.csv, forecast parameters with a row per Arps segment; tables combocurve_wells and combocurve_forecast write them alone. Columns follow ComboCurve's import article and API documentation. Its segments (default 2) and ramp (default false) are the arps table's.

  • After the fit, the rows follow the plan's EUR decline (eur.arps: its hyperbolic, then the terminal decline), scaled so ComboCurve's daily sum of the curve's rows totals the plan's EUR, so the rate steps at the last IP day (manifest.json combocurve.curve).
  • The tail starts from the fit's cumulative at that day, so its gap to the plan's EUR curve past it follows the fit's own miss there.
  • ComboCurve sums each day's start rate where Novi integrates, so its daily sums read slightly above Novi's volumes; tool_eur is that sum.
  • Di Eff-Sec is secant effective, in percent per 365.25-day year, and each segment runs from its Start Date to its End Date inclusive, the next starting the day after.
  • P-levels are series named by exceedance, as ComboCurve names them: Novi's P10 (low) as P90, Novi's P90 (high) as P10, P50 as best. Each is that level's own Arps fit and, with band_eur, EUR decline, with its own eur_check.csv rows.
  • 400s naming the fix: identity.reserves_category (ComboCurve's files carry none), columns on either table, a valnav_decline table beside either (each writes its own eur_check.csv: make two exports), and combocurve with other presets or tables.
  • manifest.json combocurve.formula_keys counts the IDs starting with =, +, - or @: wells in the well header, curves in the forecast file. A Well Name or Target Formation starting with =, +, -, @, a tab or a carriage return gets a leading '.
ComboCurve's two passes

ComboCurve keys forecast parameters on INPT ID, which it creates with each well. Load combocurve_wells.csv as a well header import, add the wells to a forecast, and export the project's well list (Chosen ID, INPT ID). Then send the same request with combocurve: {"inpt_ids": {"<Well ID>": "<INPT ID>"}} and import that export's combocurve_forecast.csv. Without the map, INPT ID holds the Well ID, and manifest.json combocurve.inpt_ids counts the wells without one.

SHAP

The shap table writes each P50 forecast's SHAP values, a row per well, design, stream, ip day and feature; shap_value and expected_value are unrounded, in the stream's unit (bbl for oil and water, mcf for gas). Formation's one-hot columns are summed into novi_formation, and zero contributions are left out. p_levels adds nothing to it.

  • The worker explains every forecast first (progress.step explain), two at a time, so a call on the same model waits behind at most two. A plan well already explained by GET .../explanations is reused; the export keeps nothing on the plan.
  • ip_days all (default) or last; top (1 to 50) keeps each row group's largest features and sums the rest into (other), as GET .../explanations' top does.
  • A forecast or stream without an explanation gets an error row, counted in manifest.json shap; an export with none explained fails with code internal and details.worker forecast.
  • At most 500 forecasts (scoped wells × designs) per export, checked before it queues: past it, a 400 on the table's table with details.max and details.count; scope it with wells or designs.
Condensate

Where the model set labels its oil slot condensate (stream_labels, GET /model-sets), or a Legacy Forecast is of condensate, oil is condensate in every file under oil's names (oil_bbl, ComboCurve's oil, Val Nav's OIL); ARIES writes CND (B/M), aries.major_stream oil. Economics prices it at the oil price and differential. manifest.json source.stream_labels holds the labels and README.txt says oil = condensate; other exports have neither.

Wells instead of a plan

source.wells takes wells as POST /plans does, up to limits.max_source_wells forecasts (wells × designs), 500 by default; GET /export-formats limits reports this server's value and, in max_source_wells_by_designs, the most wells per design count. It forecasts them in a plan of its own (unlisted, 404 by id) while progress.step is forecast, then writes the zip.

  • Labels and design names starting with =, +, -, @, a tab or a carriage return get a leading '; a plan's design names are written as they are.
  • The same wells, labels, designs and settings return the existing export.
  • Each model set forecasts up to 4 exports' wells at once, counting a cancelled export's until its forecast stops; 409 past it.
A comparison

source.comparison takes a POST /comparisons body without its pricing fields or wells (ExportComparisonSource) and writes that route's answer as tables, as Parquet too unless parquet: false. delta is b − a and delta_pct (b − a) / a × 100.

  • comparison_totals.csv, a row per total: metric, unit, ip_day, horizon_years (on the rows horizon adds), a, b, delta, delta_pct, a_wells, b_wells.
  • comparison_spread.csv, a row per side and statistic of the per-well distribution: metric, unit, ip_day, side (a, b, delta or delta_pct), statistic, value; delta rows cover mean and q50.
  • With group_by, comparison_groups.csv: group_by and group_key, then the spread's columns.
  • With include curves, comparison_curves.csv: side, stream, unit, ip_day, cum, rate, and p10 and p90 with bands. With align calendar, comparison_calendar.csv: the same by month_start.
  • With include wells, comparison_wells.csv, every pair by a_index: metric, unit, ip_day, a_index, b_index, label, b_label, a, b, delta, delta_pct, band_position.
  • manifest.json comparison holds each side as POST /comparisons echoes it and the warnings; with pairing, the pairs (method, a_only and b_only with counts), the per-well summary and include inputs' input changes. README.txt says it in words.
  • A text cell (a label, or a formation or scenario in group_key) starting with =, +, -, @, a tab or a carriage return gets a leading '.
  • A side that is missing, running, failed or on another model set, and any other 400 the body gets, answers as POST /comparisons does, field under source.comparison.
  • The tables are fixed: preset, tables, wells, designs, scenario, streams, p_levels, aries, flags, identity and source.comparison.wells are a 400, sent or null, as is a source.comparison that isn't an object.
  • The same comparison of the same plans (defaults filled in) returns the existing export. It counts against each side's plan's queue limit, and GET /exports?plan= lists it under either.
  • Its source is kind: comparison, plan null, comparison naming both sides. The file is comparison-export-<date>.zip unless name is sent.
A Legacy Forecast

source.plan takes a Legacy Forecast's id from GET /plans?origin=all, and the same writers write it: its curves and EUR are the run's, with Arps segments fitted here. manifest.json source adds origin and, on a condensate run, stream_labels.

  • streams defaults to the run's streams; a stream it didn't forecast is a 400 naming those it did.
  • The neighbors, calc_features, subsurface, shap and economics tables, and the plan_tables, drivers, economics and aries presets, are a 409 with details.reason fe_plan_unsupported.
  • identity.well_id defaults to id, the run's unique well key, the same in every export of the run, so same-named wells export; names stay in Well Name and eur_check.csv's well. With "name", two wells of one name are a 400 naming both.
  • ComboCurve's files and the monthly cumulatives at each 30-day IP day for P50, P10 and P90 of a run with bands, in one call (monthly.csv's at month m is the run's at IP day 30 × m):
    • {"source": {"plan": "<id>"}, "tables": [{"table": "combocurve_wells"}, {"table": "combocurve_forecast"}, {"table": "monthly", "horizon": "forecast", "values": ["cumulative"], "totals": false}], "p_levels": ["P50", "P10", "P90"], "parquet": false}
Callbacks

With callback_url, the server POSTs {"type": "export.done" | "export.failed", "export": <the export, as GET /exports/{id} returns it, less callbacks>} once the export is done or fails (not when it is cancelled).

  • Only to hosts the server allows (GET /export-formats callbacks; else a 400 on callback_url), at public https addresses.
  • Up to 5 URLs per export: the same request with another callback_url adds it, and sends it at once when the export is already done.
  • 3 retries, after 2 s, 15 s and 60 s; each attempt, DNS lookup included, has 10 s. Any 2xx is delivered; callbacks on the export shows each delivery.
  • Verify X-Export-Signature when callbacks.signed: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>"> with the server's shared secret. Refuse a t more than 5 minutes from your clock.
  • Dedupe on X-Export-Delivery, one id per export and URL that every retry repeats; X-Export-Id and X-Export-Event come with it.

A receiver should answer 2xx quickly, then download the file from export.file.url: the payload never inlines it.

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

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

Header parameters

  • Idempotency-KeystringOptional

    pattern ^[A-Za-z0-9._:-]{1,128}$

    Makes a retry safe: send your own key (a UUID, or your request id) and the same key on every retry. Without the header, nothing changes.

    The same key and body (compared as JSON, key order ignored) within 24 hours replays what the first request made, with its id, in its current state, with Idempotent-Replayed: true, and starts nothing. A different body is a 409 (details.field Idempotency-Key).

    • Keys are per operation, and only a success records one: retry a 502, 503, 504 or a lost response with the same key.
    • With Redis, POST /saved/{collection}, /forecast-sources and /area-sets keep keys there, as do POST /plans and /exports on a server with a state store: every server task shares them and a restart keeps them. While Redis isn't answering, these answer 503.
      • A retry while the first request is still being made waits up to 30 s for it, then answers 409: retry shortly with the same key.
      • A key the first request hasn't recorded within a minute (its task stopped, or Redis failed as it finished) lapses; a retry then makes the resource again.
    • Otherwise keys live in the server process's memory, the latest 1,000 per operation: a restart (a deploy is one) forgets them, and a retry during the first request waits for it.
    • POST /forecasts with async: true and POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans with dry_run: true neither keeps nor replays its key.
    • A replay of a plan or export the server has dropped is a 404.

Request bodyRequired

application/json

The plan or wells, the preset or tables, and a callback URL.

  • sourceobjectRequired

    What to export: a done plan, wells to forecast first, or a comparison of two plans.

    ShowHide 3 variants

    One of

    • ExportPlanSource object

      A done plan.

      • planstringRequired

        Format uuid

        A done plan's id, from POST /plans.

    • ExportWellsSource object

      Wells the export forecasts first, in a plan of its own.

      • kindstringRequired

        What the wells are, which names the file: drawn (drawn-well-…), pad (pad-…) or optimizer (optimizer-…).

        "drawn""pad""optimizer"
      • wellsarray of objectsRequired

        1 to 500 items

        The wells; up to limits.max_source_wells forecasts (500 by default; GET /export-formats reports this server's) divided by the number of designs.

        ShowHide 18 child fields in each item
        • shl[number, number]Required

          Surface hole location, [lng, lat].

        • bhl[number, number]Required

          Bottom hole (toe) location, [lng, lat]. The lateral runs from heel, else shl, to bhl and must be 100 to 50,000 ft long.

        • formationstring or nullOptional

          Target formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD.

        • tvd_ftnumber or nullOptional

          > 0, < 40000

          True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.

        • landing_below_top_ftnumber or nullOptional

          > -40000, < 40000

          Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's subsurface_sampling (GET /model-sets).

        • heel[number, number] or nullOptional

          Where the lateral starts, [lng, lat], when not at shl, the surface hole; absent or null, it starts at shl. shl must be within 50,000 ft of it.

          With it, the lateral length and its 100 to 50,000 ft check, spacing, gun barrel laterals, PDP wells and model analogs run from heel to bhl. Subsurface grids still sample at shl and bhl as the set's subsurface_sampling says, and structure tops, landing, TVD estimates, the KB elevation and the model's surface hole inputs stay at shl.

        • typed_lateralobject or nullOptional

          A lateral length typed for the well, as an inventory file gives it: length_ft, and the heel (the well's heel, else its shl) and bhl it was typed for.

          The model gets length_ft as novi_lateral_length, and spacing, the completion totals, analogs, normalize_lateral_ft and pricing use it, while the well's heel (else shl) and bhl equal those two exactly and it is within 5% of the length measured between them or within 100 to 50,000 ft; otherwise the measured length. A client that moves an end can send it unchanged: the well then uses the measured length.

          Reads give the length used as lateral_length_ft, with lateral_length_source. Optional: absent or null, the measured length.

          POST /inventories/read sets it from a file's stated length unless that is both more than 5% off the drawn one and outside 100 to 50,000 ft, with an issue when it is more than 5% off.

          ShowHide 3 child fields
          • length_ftnumberRequired

            ≥ 0, ≤ 1000000

            The typed length, ft.

          • heel[number, number]Required

            Where the lateral started when the length was typed: the well's heel, else its shl, [lng, lat].

          • bhl[number, number]Required

            The bottom hole the length was typed for, [lng, lat].

        • landing_fractionnumber or nullOptional

          ≥ 0, ≤ 1

          Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.

          The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.

          The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.

          Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.

          Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:

          • its formation has no grid there or no place in the column;
          • no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
          • the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
          • top and base averaged over the ends are under a foot apart: the zone pinches out.

          A well's inputs echo it when it was sent.

        • lateral_length_ftnumber or nullOptional

          Ignored, as in POST /plans.

        • padnumber or string or nullOptional

          The pad the well is on: a whole number, as POST /layouts/fill numbers them, or text of 1 to 60 characters, trimmed; 1 and "1" are one pad.

          POST /plans keeps a valid key whenever sent, for group_by=pad and the pad= filter, and doesn't echo it on wells; other requests read it only with pads. It is checked (a 400 on a bad value) only with pads; without pads, a value that isn't a pad is ignored.

        • scenariostringOptional

          1 to 60 characters

          As in POST /plans: every well has one or none, at most 20; then the export's scenario picks one.

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          This well's fluid in bbl per lateral ft.

          Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in pads or its layout (the bench or formation entry, then overall), its entry in scenarios (formation entry, then overall), the design's formations entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.

          Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds resolved to every well's inputs in the request.

        Show all 18 fields
        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          This well's proppant in lb per lateral ft.

          Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in pads or its layout (the bench or formation entry, then overall), its entry in scenarios (formation entry, then overall), the design's formations entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.

          Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds resolved to every well's inputs in the request.

        • stage_length_ftnumber or nullOptional

          > 0, < 2000

          Stage length in ft.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • clusters_per_stagenumber or nullOptional

          > 0, < 100

          Perforation clusters per stage; fractions are accepted.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • frac_rate_bbl_per_minnumber or nullOptional

          > 0, < 500

          Frac pump rate in bbl per minute.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • declineobjectOptional

          EUR settings for this well; needs eur on.

          With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

          Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

          A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

          ShowHide 7 child fields
          • eur_yearsintegerOptional

            ≥ 10, ≤ 50

            Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.

          • terminal_declinenumberOptional

            ≥ 0.01, ≤ 0.2

            Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.

          • b_minnumberOptional

            ≥ 0, ≤ 2.5

            Lowest hyperbolic b the fit may use; below b_max.

          • b_maxnumberOptional

            ≥ 0, ≤ 2.5

            Highest hyperbolic b the fit may use; above b_min.

          • oilobjectOptional

            Oil's own settings over these.

            ShowHide 3 child fields
            • terminal_declinenumberOptional

              ≥ 0.01, ≤ 0.2

              Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.

            • b_minnumberOptional

              ≥ 0, ≤ 2.5

              Lowest hyperbolic b the fit may use; below b_max.

            • b_maxnumberOptional

              ≥ 0, ≤ 2.5

              Highest hyperbolic b the fit may use; above b_min.

          • gasobjectOptional

            Gas's own settings over these.

            Same fields as StreamDeclineSettings.

          • waterobjectOptional

            Water's own settings over these, only with eur_water: true, else a 400. Unlike oil and gas it doesn't set per-stream settings: oil and gas keep theirs and their calls.

            Same fields as StreamDeclineSettings.

        • labelstring or nullOptional

          up to 100 characters

          The well's name in every table (the well column). Default Drawn well for one drawn well, else Well 1, Well 2, …; each well's must differ.

      • designsarray of objectsOptional

        1 to 10 items

        Completion designs; every well is forecast with each. Leave out for one design at the recent-completions median. A well's own completions, a scenario's and a pad's or layout's need one design.

        ShowHide 7 child fields in each item
        • namestring or nullOptional

          up to 60 characters

          Your name for the design; defaults to Design 1, Design 2, ….

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

        • stage_length_ftnumber or nullOptional

          > 0, < 2000

          Stage length in ft.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • clusters_per_stagenumber or nullOptional

          > 0, < 100

          Perforation clusters per stage; fractions are accepted.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • frac_rate_bbl_per_minnumber or nullOptional

          > 0, < 500

          Frac pump rate in bbl per minute.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • formationsarray of objectsOptional

          Per-formation overrides, each formation at most once.

          ShowHide 6 child fields in each item
          • formationstringRequired

            Formation (case-insensitive).

          • fluid_bbl_per_ftnumber or nullOptional

            > 0, < 1000

            Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

          • proppant_lb_per_ftnumber or nullOptional

            > 0, < 20000

            Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

          • stage_length_ftnumber or nullOptional

            > 0, < 2000

            Stage length in ft.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

          • clusters_per_stagenumber or nullOptional

            > 0, < 100

            Perforation clusters per stage; fractions are accepted.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

          • frac_rate_bbl_per_minnumber or nullOptional

            > 0, < 500

            Frac pump rate in bbl per minute.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • scenariosarray of objectsOptional

        1 to 20 items

        Values for each scenario's wells, keyed by the scenario the wells name; a scenario without an entry takes the request's values.

        A well's own completions, til_date and landing beat its scenario's, as do its pad's and its layout's or bench's. A scenario's completions beat the design's, and its til_date and pdp the request's. Once an entry sets completions, every well's inputs.resolved gives them. Once one sets a TIL date or landing that a well takes, inputs.resolved gives each well's til_date and landing, and the export's wells table adds til_date, til_layer and landing_layer.

        A 400 naming the entry refuses a name no well has, a repeated name, scenarios when no well has a scenario, and completions in it under more than one design.

        ShowHide 10 child fields in each item
        • namestringRequired

          1 to 60 characters

          The scenario these values are for: exactly a name on the request's wells or layouts, trimmed, at most 60 characters, each once.

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          Fluid in bbl per lateral ft for the scenario's wells: below a well's own, its pad's and a formations entry here, above the design's values. Needs one design, or none.

        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          Proppant in lb per lateral ft for the scenario's wells, as fluid_bbl_per_ft is set.

        • stage_length_ftnumber or nullOptional

          > 0, < 2000

          Stage length in ft.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • clusters_per_stagenumber or nullOptional

          > 0, < 100

          Perforation clusters per stage; fractions are accepted.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • frac_rate_bbl_per_minnumber or nullOptional

          > 0, < 500

          Frac pump rate in bbl per minute.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • til_datestring or nullOptional

          Format date

          TIL date for the scenario's wells without their own or their pad's or layout's, over the request's til_date.

          TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.

          From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.

        • pdpboolean or nullOptional

          Whether this scenario's wells space against existing (PDP) wells, over the request's pdp, so scenarios in one request can differ.

        • declineobjectOptional

          EUR settings for the scenario's wells; needs eur on.

          With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

          Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

          A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

          Same fields as DeclineSettings.

        • formationsarray of objectsOptional

          up to 100 items

          Values for the scenario's wells in one formation, each formation at most once. The only place a scenario sets landing.

          ShowHide 10 child fields in each item
          • formationstringRequired

            Formation (case-insensitive; GET /formations lists them).

          • fluid_bbl_per_ftnumber or nullOptional

            > 0, < 1000

            Fluid in bbl per lateral ft for this formation's wells in the scenario or pad, over the entry's own. Needs one design, or none.

          • proppant_lb_per_ftnumber or nullOptional

            > 0, < 20000

            Proppant in lb per lateral ft, as fluid_bbl_per_ft is set.

          • stage_length_ftnumber or nullOptional

            > 0, < 2000

            Stage length in ft.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

          • clusters_per_stagenumber or nullOptional

            > 0, < 100

            Perforation clusters per stage; fractions are accepted.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

          • frac_rate_bbl_per_minnumber or nullOptional

            > 0, < 500

            Frac pump rate in bbl per minute.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

          • tvd_ftnumber or nullOptional

            > 0, < 40000

            True vertical depth in ft. Landing falls through as one unit: a well, or a narrower layer, that sets any of tvd_ft, landing_below_top_ft or landing_fraction keeps its own, so this reaches only wells that set none.

          • landing_below_top_ftnumber or nullOptional

            > -40000, < 40000

            Instead of tvd_ft: ft below the formation top, as on a well.

          • landing_fractionnumber or nullOptional

            ≥ 0, ≤ 1

            Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.

          • declineobjectOptional

            EUR settings for this formation's wells in the scenario or pad; needs eur on.

            With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

            Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

            A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

            Same fields as DeclineSettings.

      • padsarray of objectsOptional

        at least 1 items

        Values for each pad's wells, keyed by the pad the wells name; a well on no listed pad takes the layers below. An entry may hold only pad and name.

        A well's own completions, til_date and landing beat its pad's, an entry's formations beat its own values, and a pad beats its wells' scenarios. Once an entry sets completions, every well's inputs.resolved gives them. Once one sets a TIL date or landing that a well takes, inputs.resolved gives each well's til_date and landing, and the export's wells table adds til_date, til_layer and landing_layer.

        A 400 naming the field refuses:

        • a pad no well has, or a repeat (1 and "1" are one pad);
        • a bad pad on any well;
        • over 200,000 formations entries across the list;
        • pads with layout or layouts, whose own fields set their wells;
        • a well with no formation that takes landing_below_top_ft or landing_fraction from an entry's own values;
        • completions in it under more than one design.
        ShowHide 13 child fields in each item
        • padinteger or stringRequired

          1 to 60 characters

          The pad these values are for: an integer or text as the wells name it, trimmed, at most 60 characters, each once; 1 and "1" are one pad.

        • namestring or nullOptional

          up to 60 characters

          The pad's name, 1 to 60 characters once trimmed; null is none, and a blank name is a 400. Names needn't be unique: the key still groups and orders pads, pairs them in comparisons and filters with pad=.

          POST /plans keeps it: the economics export's pad column writes it instead of the key on well and pad rows, GET /plans/{id}/stats?group_by=pad gives it as groups[].name, GET /plans/{id}/rollup as pads[].name, and the type curve, plan economics and comparisons by pad give it beside the key. POST /forecasts and POST /exports source check it but don't use it.

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          Fluid in bbl per lateral ft for the pad's wells: below a well's own and a formations entry here, above a scenario's and the design's. Needs one design, or none.

        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          Proppant in lb per lateral ft for the pad's wells, as fluid_bbl_per_ft is set.

        • stage_length_ftnumber or nullOptional

          > 0, < 2000

          Stage length in ft.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • clusters_per_stagenumber or nullOptional

          > 0, < 100

          Perforation clusters per stage; fractions are accepted.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • frac_rate_bbl_per_minnumber or nullOptional

          > 0, < 500

          Frac pump rate in bbl per minute.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • til_datestring or nullOptional

          Format date

          TIL date for the pad's wells without their own, over a scenario's and the request's til_date.

          TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.

          From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.

        • tvd_ftnumber or nullOptional

          > 0, < 40000

          True vertical depth in ft for the pad's wells. Landing falls through as one unit, so a well, or a formations entry here, that sets any landing field keeps it.

        • landing_below_top_ftnumber or nullOptional

          > -40000, < 40000

          Instead of tvd_ft: ft below the top of each well's own formation; a well that takes it needs one.

        • landing_fractionnumber or nullOptional

          ≥ 0, ≤ 1

          Instead of tvd_ft or landing_below_top_ft: 0 at the top of each well's own formation to 1 at its base; a well that takes it needs one.

        • declineobjectOptional

          EUR settings for the pad's wells; needs eur on.

          With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

          Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

          A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

          Same fields as DeclineSettings.

        • formationsarray of objectsOptional

          up to 100 items

          Values for the pad's wells in one formation, each formation at most once.

          Same fields as ScenarioFormationInput.

      • formationsarray of objectsOptional

        up to 100 items

        The request's landing per formation, each formation at most once; a landing on the well, its pad, layout, bench or scenario entry beats it. Goes with wells.

        An entry for a formation no well has is accepted. Completions per formation stay in designs. Once an entry sets a landing that a well takes, inputs.resolved gives each well's til_date and landing, and the export's wells table adds til_date, til_layer and landing_layer.

        ShowHide 5 child fields in each item
        • formationstringRequired

          Formation (case-insensitive; GET /formations lists them).

        • tvd_ftnumber or nullOptional

          > 0, < 40000

          True vertical depth in ft for the request's wells in this formation that no narrower layer lands.

        • landing_below_top_ftnumber or nullOptional

          > -40000, < 40000

          Instead of tvd_ft: ft below the formation top, as on a well.

        • landing_fractionnumber or nullOptional

          ≥ 0, ≤ 1

          Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.

        • declineobjectOptional

          EUR settings for the request's wells in this formation; needs eur on.

          With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

          Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

          A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

          Same fields as DeclineSettings.

      • til_datestringOptional

        Format date

        TIL date, YYYY-MM-DD, for every well no narrower layer dates, as POST /plans takes it.

      • pdpbooleanOptional

        Default true

        Space against existing (PDP) wells. A scenario's pdp in scenarios beats it, and this stays the manifest's pdp.

      • eurbooleanOptional

        Fit EUR for monthly volumes to EUR and the EUR summary. Default true when the server has EUR (GET /dataset eur.available; when the forecast worker doesn't answer within 1.5 s, its last ready answer, else a 503), or when decline is sent at any layer or eur_water is true; true answers 503 without it.

      • eur_waterbooleanOptional

        Default false

        Fit water's EUR too, with decline.water over the settings at any layer.

        Adds eur to each water forecast, water to the decline echo, totals[].eur and inputs.resolved.decline, and water's columns to the eur, forecast and wells tables, where monthly water runs to the EUR day. BOE never reads it, and oil's and gas's fits are unchanged. Without it, decline.water is a 400. With eur left out it turns EUR on, as decline does; with eur: false it is a 400 on source.eur_water.

      • declineobjectOptional

        Decline fit settings, as on POST /plans.

        Same fields as DeclineSettings.

      • depletion_chainbooleanOptional

        Chain depletion in the export's plan, as POST /plans' depletion_chain does: on by default where GET /dataset depletion_chain.available is true, else off, and false turns it off. The export's source.depletion_chain echoes it where the plan would.

      • namestring or nullOptional

        up to 100 characters

        A name for the wells, as a plan name: the export's title when it has none.

    • ExportComparisonSource object

      A comparison of two done plans or scenarios, written as its tables.

      • comparisonobjectRequired

        Two plan sides and what to measure, as POST /comparisons takes them, but without wells (the download writes every pair, by a_index) or the pricing fields deck_id, deck, conventions and include value: each is a 400 here, as is a forecast source side.

        ShowHide 10 child fields
        • aobjectRequired

          Side a, the base: delta is b − a and delta_pct is relative to it.

          ShowHide 3 child fields
          • planstringRequired

            Format uuid

            A done plan's id, as POST /plans returns it.

          • scenariostringOptional

            1 to 60 characters

            On a plan made with scenarios, the scenario to compare, exactly as its scenarios list it; required there, and a 400 on a plan without scenarios. A name it doesn't have is a 400 whose details.scenarios lists them.

          • designintegerOptional

            Default 0≥ 0

            The design, as its index in the plan's designs; 0 by default. One past the last is a 400.

        • bobjectRequired

          Side b. It may be the plan of side a, with another scenario or design.

          Same fields as ComparisonSide.

        • metricstringOptional

          The per-well metric distribution, groups and curves measure: eur_boe by default when both sides have EUR, else cum_boe.

          Per-well metrics: eur_oil (bbl), eur_gas (mcf) and eur_boe (BOE) are each well's EUR and need a plan made with eur: true (400 otherwise); cum_oil, cum_gas and cum_boe are the forecast's cumulative volume at ip_day. BOE is oil + gas / 6, only for wells with both.

          "eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"
        • ip_dayintegerOptional

          ≥ 1

          For a cum_ metric, the ip_day to measure, one of the forecast ip_days GET /dataset lists; 1080 by default. With an eur_ metric it is a 400.

        • normalize_lateral_ftnumberOptional

          ≥ 100, ≤ 20000

          Scale each well's value to this lateral length in distribution and groups, as GET /plans/{id}/stats does: value × normalize_lateral_ft / its lateral_length_ft. Totals and curves stay unscaled. 100 to 20,000.

        • group_bystringOptional

          Also compare each group of wells: design (every design index either side has), formation (each well's target formation, null for none), scenario (a 400 when neither side's plan has scenarios), or pad (the pad key, null for wells without one; 400 when neither plan has keys). Pads pair by key in side a plan order then new side b keys, null last, without a cap or Other row.

          "design""formation""scenario""pad"
        • includearray of stringsOptional

          Optional parts. Any other value is a 400 listing these.

          "curves""bands""wells""inputs"
        • pairobjectOptional

          How to pair the sides' wells; adds pairs to the answer.

          ShowHide 3 child fields
          • bystringOptional

            Default "auto"

            auto (default): name when every well on both sides has a real name and none repeats on a side, else location; with a forecast source side, saved, else name, else uwi.

            • name: names found once on each side; a repeated name's wells pair by location within it.
            • location: heel and bottom hole each within tolerance_ft; same formation first, then closest, then nearest TVD; one to one.
            • index: by position, with a warning.
            • map: the pairs in map.
            • uwi and saved: forecast source sides only; location and index: plan sides only.
            "auto""name""location""index""map""uwi""saved"
          • tolerance_ftnumberOptional

            Default 300≥ 1, ≤ 5280

            With auto or location: how far apart, ft, a pair's heels (else surface holes) and bottom holes may each be; 300 by default. With another by it is a 400.

          • maparray of arraysOptional

            Items 2 items

            With by map, and only then: the pairs, each well once; an index or Well ID outside its side's wells or used twice is a 400 naming the entry (pair.map[k]).

        • horizonstring or objectOptional

          Each side's cumulative at a common horizon beside its EUR; needs EUR on both sides (a 400 naming the side without).

          ShowHide 2 variants

          Any of

          • own: each side's EUR only, the default string

            own: each side's EUR only, the default.

            "own"
          • Option 2 object

            A common horizon: cumulative rows at that many years.

            • yearsintegerRequired

              ≥ 1, ≤ 50

              Years.

        • alignstringOptional

          calendar adds curves.calendar, each side's curve by calendar month (needs include curves and a well with a TIL date on each side, or a start date on every well of a forecast source side); months_on, the default, adds nothing.

          "months_on""calendar"
  • presetstringOptional

    A preset id from GET /export-formats, as engineer. Not with tables.

  • tablesarray of objectsOptional

    1 to 14 items

    The tables to write, each once, with their options. Not with preset.

    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 nullOptional

    1 to 100000 itemsItems ≥ 0

    Only these plan wells, by index in the plan (repeats count once); null or absent for all of them. Up to 10,000 indexes, or as many as the plan has wells when it has more.

  • designsarray of integers or nullOptional

    1 to 10000 itemsItems ≥ 0

    Only these designs, by index in the plan (repeats count once); null or absent for all of them.

  • scenariostringOptional

    1 to 60 characters

    Instead of wells: only this scenario's wells, of a plan (or source wells) made with scenarios; a 400 with wells, on a plan without scenarios, or naming none of its scenarios (details.scenarios lists them).

  • streamsarray of stringsOptional

    1 to 200 items

    Only these streams' columns (default all three).

    "oil""gas""water"
  • namestring or nullOptional

    up to 100 characters

    Your name for the export; the zip's file name is this plus .zip.

  • callback_urlstring or nullOptional

    up to 2048 characters

    Where to POST the export once it is done or fails: https, to a host the server allows (GET /export-formats callbacks).

  • parquetbooleanOptional

    Default true

    Also write fixed-schema tables as Parquet under parquet/, with export_id and Snowflake and Databricks load scripts. Tables whose GET /export-formats parquet is false are CSV only. true with preset aries is a 400 (a text file).

  • p_levelsarray of stringsOptional

    1 to 200 items

    The P-levels the monthly, eur, arps, valnav_decline and combocurve_forecast tables write, a row each (P50, P10, P90), and the blocks preset aries writes. Default P50 alone, even on a plan with bands.

    P10 and P90 need a plan made with bands: true (409 without); p_levels needs a table with P-levels or preset aries (400 without). combocurve_forecast writes each as a series: P50 as best, Novi's P10 (low) as P90, its P90 (high) as P10; combocurve_wells writes none. 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).

    "P50""P10""P90"
  • ariesobjectOptional

    With preset aries only (400 otherwise): its options, each with a default.

    ShowHide 6 child fields
    • compatstringOptional

      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_streamstringOptional

      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_keystringOptional

      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 nullOptional

      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.

    • cleanbooleanOptional

      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"
Show all 17 fields
  • identityobjectOptional

    Well ID, start date and reserves category for the economics presets; only a preset or table that reads a field takes it.

    GET /export-formats?include=identity lists the fields of each preset (presets[].identity) and table (tables[].identity): valnav_decline reads all three, the combocurve tables well_id and start_date.

    • With tables, a field none of them lists is a 400 naming it.
    • With another preset, or tables none of which reads identity, it is a 400 naming the presets and tables that do; a planned preset first answers that it isn't available yet.
    • Not an object, or an unknown field: a 400 listing the three.
    • With preset aries it resolves into aries's options before the export is keyed, so a request with identity or with aries shares one export (the second answers reused: true); the job echoes aries alone.
    • With valnav and combocurve it is resolved, defaults filled, so a request with or without the defaults shares one export; the job echoes it resolved.
    ShowHide 3 child fields
    • well_idstringOptional

      Default "name"

      Each well's Well ID: name (the default) writes its name, else its plan label (Plan well N); id its plan well id, as DRAWN-0; uid its well_uid from GET /plans/{id}/curves.

      • On a Legacy Forecast the default is id, its unique well key: a run's well names can repeat.
      • uid is 32 characters, the same on every read of the plan, so plans whose wells share names or ids get different Well IDs.
      • With preset aries it is aries.well_key: send either, or the same value in both (null counts as not sent); different values are a 400 naming both.
      • A 400 naming identity.well_id: id or uid on a plan well without an id, name on a well whose name has no visible character, uid with preset aries or on wells sent in source (a new plan each export).
      "name""id""uid"
    • start_datestringOptional

      Default "til"pattern ^(til|\d{4}-\d{2}-\d{2})$

      Each well's start date: til (the default) writes its TIL date, else the plan's day; a real day as YYYY-MM-DD, 1900-01-01 to 2199-12-31, sets that day for every well.

      Anything else is a 400 naming identity.start_date. With preset aries it is aries.start_date (til as null or left out): send either, or the same value in both (null counts as not sent); different values are a 400 naming both.

    • reserves_categorystringOptional

      Default "PUD"1 to 40 characters

      The reserves category written for every well, 1 to 40 characters with no control characters, PUD when left out. Only presets that write one read it: valnav writes it as Rescat (for P50; reserves_categories names P10's and P90's); ARIES and ComboCurve write none, so with preset aries or combocurve it is a 400.

  • reserves_categoriesobjectOptional

    With preset valnav or the valnav_decline table only (400 otherwise): the Rescat Val Nav's file writes per P-level; P50's replaces identity.reserves_category.

    P10 and P90 each need their own when p_levels sends them (two on one category is a 400); a level not in p_levels is a 400 naming it. Novi never maps P-levels to 1P, 2P or 3P: its P10 is the low curve, PRMS's P90.

    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

    With preset combocurve or its tables only (400 otherwise): what ComboCurve's forecast parameters file keys each well on, for the second pass. Part of the export's key.

    ShowHide 1 child field
    • inpt_idsobjectOptional

      Each Well ID's INPT ID, from the ComboCurve project's well list once combocurve_wells.csv is loaded, keyed by the Well IDs (Chosen IDs) in this export. Wells left out keep their Well ID as INPT ID.

      A 400 names the entry for an unknown key, a repeated value (compared as written, a lone surrogate as U+FFFD), a control character, or a left-out well's Well ID as value.

  • economicsobjectOptional

    With the economics table or preset only (else a 400 on economics). deck_id, deck and conventions as POST /economics takes them; left out, the plan model set's default deck and prototype conventions.

    fe counts with monthly discounting and whole-month payback. The resolved deck and conventions, defaults included, are part of the export key.

    ShowHide 3 child fields
    • deck_idstringOptional

      The deck to price with, one GET /economics/decks lists for the set; left out, the set's default deck (prototype-midland-flat; illustrative-haynesville-gas on a Haynesville set).

      "prototype-midland-flat""house-70-3""illustrative-haynesville-gas"
    • deckobjectOptional

      Overrides of the deck's values for this request (every deck takes the same ranges); any left out keep the deck's.

      ShowHide 20 child fields
      • oil_pricenumberOptional

        ≥ 0, ≤ 300

        $/bbl; 75 in the illustrative Midland deck.

      • oil_differentialnumberOptional

        ≥ -50, ≤ 50

        $/bbl; 4 in the illustrative Midland deck.

      • gas_pricenumberOptional

        ≥ 0, ≤ 50

        $/mcf; 3.5 in the illustrative Midland deck.

      • gas_differentialnumberOptional

        ≥ -10, ≤ 10

        $/mcf; 1 in the illustrative Midland deck.

      • ngl_pricenumberOptional

        ≥ 0, ≤ 200

        $/bbl; 26 in the illustrative Midland deck.

      • ngl_yield_bbl_per_mmcfnumberOptional

        ≥ 0, ≤ 300

        bbl/MMcf; 130 in the illustrative Midland deck.

      • shrinknumberOptional

        ≥ 0, ≤ 1

        fraction; 0.8 in the illustrative Midland deck.

      • opex_oilnumberOptional

        ≥ 0, ≤ 100

        $/bbl; 5.5 in the illustrative Midland deck.

      • opex_gasnumberOptional

        ≥ 0, ≤ 20

        $/mcf; 0.5 in the illustrative Midland deck.

      • opex_waternumberOptional

        ≥ 0, ≤ 20

        $/bbl; 0.6 in the illustrative Midland deck.

      • royaltynumberOptional

        ≥ 0, ≤ 0.5

        fraction; 0.25 in the illustrative Midland deck.

      • severance_oilnumberOptional

        ≥ 0, ≤ 0.5

        fraction; 0.046 in the illustrative Midland deck.

      Show all 20 fields
      • severance_gasnumberOptional

        ≥ 0, ≤ 0.5

        fraction; 0.075 in the illustrative Midland deck.

      • ad_valoremnumberOptional

        ≥ 0, ≤ 0.2

        fraction; 0.025 in the illustrative Midland deck.

      • capex_per_wellnumberOptional

        ≥ 0, ≤ 50000000

        $; 2500000 in the illustrative Midland deck.

      • capex_drilling_per_ftnumberOptional

        ≥ 0, ≤ 2000

        $/ft; 150 in the illustrative Midland deck.

      • capex_stimulation_per_ftnumberOptional

        ≥ 0, ≤ 2000

        $/ft; 125 in the illustrative Midland deck.

      • capex_proppant_per_lbnumberOptional

        ≥ 0, ≤ 2

        $/lb; 0.08 in the illustrative Midland deck.

      • capex_fluid_per_bblnumberOptional

        ≥ 0, ≤ 50

        $/bbl; 3 in the illustrative Midland deck.

      • discount_ratenumberOptional

        ≥ 0, ≤ 1

        fraction per year; 0.25 in the illustrative Midland deck.

    • conventionsstringOptional

      Default "prototype"

      How NPV and payback are counted: prototype, yearly discounting (the app's default), or fe, monthly discounting, which matches Novi's earlier Forecast Engine.

      "prototype""fe"
  • flagsbooleanOptional

    Default false

    With preset, or neither (the default preset): true adds flagged and out_of_range columns to the preset's eur, wells and forecast tables. Default false.

    flagged: whether a design's inputs (in wells, any exported design's) fall outside the model's training data. out_of_range: each such input with its value and range. GET /export-formats describes both.

    • They follow the other columns (on a plan's wells table, before its layer columns and scenario), in CSV, and in Parquet for eur and wells; nothing else changes.
    • The export and manifest.json echo flags: true; their eur, wells and forecast tables list the resolved columns.
    • With tables, true is a 400 (list both in each table's columns), as is a preset with none of those tables (aries).

Responses

The identical export, already done (reused: true).

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

    Same fields as ExportTable.

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

409

A conflict with the plan, the queue, the callbacks or the Idempotency-Key.

  • The plan is running or failed, or a table needs EUR the plan or wells don't have.
  • The model set or plan has as many exports queued or running as it takes, or the model set is forecasting as many exports' wells as it takes.
  • The export has 5 callbacks.
  • The Idempotency-Key was used with a different body; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key.
413

The request body is over 10 MB.

503

A model worker or the subsurface grids aren't ready, or, with Redis, the Redis that keeps Idempotency-Key records isn't answering; retry shortly with the same key.

Shared errors400401403500What they mean