Skip to content
Developers
Get an API token

Get a plan

A plan's status, progress and designs and, once it is done, its totals per design (each stream summed over the wells with a forecast).

Get a plan

GET/plans/{id}

A plan's status, progress and designs and, once it is done, its totals per design (each stream summed over the wells with a forecast). include=wells adds its wells.

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

include=wells adds each well's inputs, TVD, forecasts per design and spacing summary, in plan order, all of them unless you page with limit and cursor. sort ranks them (include=wells&sort=eur_boe&limit=10 is the top ten by BOE EUR); fields, wells, scenario, formation, pad, q, designs and ip_days cut them down, each as its parameter says. A failed plan returns no wells.

While it runs

The answer carries Retry-After: 1 and no ETag; send wait instead of polling. include=wells returns the wells finished so far, in finish order, and its next_cursor keeps paging in that order after the plan is done, so a poll fetches only new wells and gets every well once. sort answers 409 meanwhile; GET /plans/{id}/stats answers partial figures.

A plan running on another server lists no wells until it is done, and next_cursor stays where yours was. Its checks that need its wells or designs (a scenario or pad it lacks, a designs or design index past its designs, every eur_curve check but its value) answer once it is done; the rest answer at once.

Caching

A done or failed plan's answer carries an ETag; send it as If-None-Match for a 304.

Legacy Forecasts

GET /plans?origin=all lists the tenant's Legacy Forecasts beside its plans, each read only. A Legacy Forecast is a done predrill run of Novi's earlier Forecast Engine, with its wells, forecasts, EUR and, where the run has them, P10 and P90 bands. GET /plans/{id}, its wells and curves, GET /export-formats?plan= and POST /exports read one, with v2's own Arps fits on the run's curves; any other operation naming one is a 409 with details.reason fe_plan_unsupported, and a change (PATCH, DELETE, a share, economics, from_plan) one with plan_read_only.

A Legacy Forecast's exports skip ARIES and the tables the run has no data for, with the presets that need them (GET /export-formats says why). A run that forecast only some streams carries only those, and an export defaults streams to them (another is a 400); condensate sits in the oil stream, with stream_labels {"oil": "condensate"}. A run whose results file can't be read is a failed plan (error.code unavailable, no links.export) that the server reads again later, and when the file changes. A Legacy Forecast always carries origin, streams and stream_labels; its one design is As run, its wells carry their own completions, and include=storage answers storage: null.

Retention

With a state store, an unsaved plan is kept for the server's scratch period after it is made (90 days unless the server sets another; storage.expires_at says when) and deleted within a minute of expires_at; a saved plan is kept until deleted. Saving clears expires_at; unsaving starts a new scratch period. A deleted plan is gone from the API at once, its shares revoked and its attached documents deleted.

Parameters

Path parameters

Query parameters

  • includestringOptional

    What to add, of wells, storage, decline_base, request, origin and timings. A 400 for an unknown name lists the six in details.allowed.

    • wells: per-well summaries. The wells-only parameters need it.
    • storage: retention, tenant and active share count; null without a state store.
    • decline_base: inputs.resolved.decline.base on each well that has resolved.decline, and nothing on a plan with no layer below it; older plans leave it out. Needs wells (400 without it), and with fields needs inputs kept (400 otherwise).
    • request: the body POST /plans accepted, keys as sent after an assumption set's fill, without callback_url and dry_run, so a client can show a plan's inputs and send them back. A field sent as null comes back null unless the set filled it.
      • A plan made with from_plan answers its source's body. Older plans, and plans made through the legacy POST /api/plan or re-run from one, answer null. Without a state store it is a 409.
    • origin: origin, streams and stream_labels.
    • timings: where the plan's time went per worker step; alone, it reads no more of the plan than a GET without include.

    When any but wells is named, names may be comma-separated or repeated, each once, and unknown or duplicate names are a 400. Otherwise only the first include value is read, and it must be exactly wells or empty (spaces and unknown values are a 400). The schema lists every set of names this operation takes; the same names in another order are taken too.

    "wells""storage""wells,storage""storage,wells""wells,decline_base""decline_base,wells""wells,storage,decline_base""request""wells,request""request,wells""storage,request""wells,storage,request""origin""wells,origin""storage,origin""wells,storage,origin""timings""wells,timings""storage,timings""wells,storage,timings"
    30 more values"request,origin""request,timings""origin,timings""wells,decline_base,request""wells,decline_base,origin""wells,decline_base,timings""wells,request,origin""wells,request,timings""wells,origin,timings""storage,request,origin""storage,request,timings""storage,origin,timings""request,origin,timings""wells,storage,decline_base,request""wells,storage,decline_base,origin""wells,storage,decline_base,timings""wells,storage,request,origin""wells,storage,request,timings""wells,storage,origin,timings""wells,decline_base,request,origin""wells,decline_base,request,timings""wells,decline_base,origin,timings""wells,request,origin,timings""storage,request,origin,timings""wells,storage,decline_base,request,origin""wells,storage,decline_base,request,timings""wells,storage,decline_base,origin,timings""wells,storage,request,origin,timings""wells,decline_base,request,origin,timings""wells,storage,decline_base,request,origin,timings"
  • limitintegerOptional

    Default 10000≥ 1, ≤ 10000

    With include=wells: wells per page, at most 10,000 also on a server that allows bigger plans; page the rest with cursor.

  • cursorstringOptional

    Page to read: next_cursor from the previous page. One from a running plan keeps paging in finish order after the plan is done, so a client polling with it gets every well once, and it can't be sent with sort (400 once the plan is done or with wait; a running plan answers 409 to sort first).

  • sortstringOptional

    With include=wells (400 without): order the wells by this metric under design, wells without a value last in either order and ties in plan order; limit and cursor page the sorted order.

    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"
  • orderstringOptional

    Default "desc"

    With sort (ignored without it): desc, largest first, or asc.

    "asc""desc"
  • designintegerOptional

    Default 0≥ 0, ≤ 9

    With sort: the design whose forecasts are measured, as its index in the plan's designs; 400 past the last one. Also selects the design whose checks fields=checks returns, and is read and range-checked then too, even without sort.

  • ip_dayintegerOptional

    Default 1080≥ 1

    With sort (ignored without it): for a cum_ metric, the ip_day (days since first production) whose cumulative volume is measured: one of GET /dataset ip_days, default 1080 (3 years). 400 with an eur_ metric.

  • waitintegerOptional

    ≥ 1, ≤ 25

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

    Whole seconds, 1 to 25 (400 otherwise). The answer is what a GET without wait would get when the wait ends, Retry-After included; a finished job answers at once. A client that disconnects ends the wait. With include=wells it waits on the status only, not on newly finished wells, and the page is read when the answer goes out; with sort on a plan still running when the wait ends, it answers 409 as without wait.

  • fieldsstringOptional

    Only these fields, comma-separated; absent or empty, every field. index is always kept, and the response keeps its own key order.

    Allowed: with include=wells (400 without it), any of each well's fields listed below, and value with sort.

    For example label,forecasts. A well that could not be placed also always keeps error. The plan's own fields, totals and next_cursor are always there.

    The fields: index, key, label, inputs, lateral_length_ft, estimates, forecasts, spacing, checks, name, nearest_same_formation_ft, lateral_length_source.

    • value: the sort metric's value of each well, under design, ip_day and normalize_lateral_ft, rounded to 0.1 in the metric's unit (as GET /plans/{id}/stats); null for a well without one. 400 without sort. A ranking page of fields=label,value is about a tenth of one with forecasts.
    • checks: each well's checks for design (default 0), the same object as that design's forecasts[].checks, or null when that design has none (a failed well, or no checks). Readable without sort. Show the flag beside any number you quote from a well whose checks.flagged is true.
    • nearest_same_formation_ft: as the PlanWellSummary schema describes it. Readable without sort.

    Names are top-level only (no dots), case-sensitive and never empty; one not allowed here is a 400 with the allowed names in details.allowed.

  • wellsstringOptional

    With include=wells (400 without it), only these wells: their plan indexes (each row's index, from 0), comma-separated, at most 500 different ones; a repeat counts once.

    Use it to read a few wells of a big plan in one call, as wells=3,1999&fields=lateral_length_ft,forecasts. The rows come in plan order, in sort order, or after a running plan's cursor in finish order, and fields, limit and cursor work on these wells only; while the plan runs, those of them finished so far. An index the plan doesn't have, or anything but whole numbers and commas, is a 400.

  • scenariostringOptional

    1 to 60 characters

    With include=wells (400 without it), only one scenario's wells, named exactly as the plan's scenarios list it, URL-encoded: 660 ft is scenario=660%20ft.

    An empty name, or one the plan doesn't have, is a 400 whose details.scenarios lists the plan's scenarios (empty on a plan without them, where any name is a 400). A name over 60 characters is a 400 without the list.

    scenario, formation, q, pad and wells apply together, and sort, fields, limit and cursor work on the wells that pass. matched counts those wells, finished or not, while total stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.

  • formationstringOptional

    With include=wells (400 without it), only the wells landing in these formations: one name or a comma-separated list, case-insensitive, as GET /wells takes it. Empty is no filter.

    A name GET /formations doesn't list is a 400 with them in details.allowed; a listed one none of the plan's wells land in gives an empty page. A well with no formation matches none.

    scenario, formation, q, pad and wells apply together, and sort, fields, limit and cursor work on the wells that pass. matched counts those wells, finished or not, while total stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.

Show all 20 parameters
  • padstringOptional

    1 to 60 characters

    With include=wells (400 without it), only the wells on this pad: one key, not a list, trimmed; a well sent with "pad": 1 or "pad": "1" matches pad=1.

    Empty, or over 60 characters, is a 400, and so is any key on a plan whose wells name no pads. A key no well has is a 400 whose details.pads lists the plan's first 50 keys in plan order.

    scenario, formation, q, pad and wells apply together, and sort, fields, limit and cursor work on the wells that pass. matched counts those wells, finished or not, while total stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.

  • qstringOptional

    up to 100 characters

    With include=wells (400 without it), only the wells whose label, or name when they have one, contains this text, ignoring case: well 12 matches Plan well 12. Empty is no filter.

    No wildcards. Spaces at either end are ignored. Up to 100 characters (400 past it).

    scenario, formation, q, pad and wells apply together, and sort, fields, limit and cursor work on the wells that pass. matched counts those wells, finished or not, while total stays the whole plan; while the plan runs, the rows are those finished so far. A cursor holds no filter: send the same filters with it.

  • eur_curvestringOptional

    With include=wells, on a plan made with eur: true: adds each well's oil and gas EUR curve (and water's with eur_water) as eur.curve, to compare a few plan wells to EUR.

    Only on a page of at most 25 wells with month and 100 with year (a limit that small, or wells with at most that many indexes) whose fields, if sent, keep forecasts; 400 otherwise, with details.max.

    The curve: cumulative volumes to the EUR's days.

    It continues the forecast from its last ip_day on the same decline fit: month every 30 days (the export's monthly cumulatives), year every 360 days plus the EUR's day. A decline-curve extension, not a model output.

    "month""year"
  • designsstringOptional

    With include=wells (400 without it), each well's forecasts keep only these designs: their indexes in the plan's designs, comma-separated, each once and in range. Absent: every design.

    A repeat or an index out of range is a 400; past the last, details.designs is the plan's count. Kept forecasts come in the plan's design order, each with its own design index. With eur_curve, only the kept designs get curves.

    designs trims only what each well carries: design is the one design sort ranks by and value measures, and designs changes neither it, the order, value, next_cursor nor the plan's own fields.

  • ip_daysstringOptional

    With include=wells (400 without it), each kept forecast's streams hold only these ip_days, comma-separated: their values and P10/P90 bands. Absent: every ip_day.

    They are cut and checked as POST /forecasts ip_days cuts a forecast: up to 36 different ones of GET /dataset ip_days, else a 400 with them in details.allowed, and they come back ascending and once each. EURs are fit on the whole curve and don't change; with eur_curve, each curve still starts after the forecast's last ip_day before the cut. sort, ip_day and value don't change.

    A cut that starts after 30 or skips an ip_day can't be sent to POST /economics as curves (a 400): price the plan by reference, which uses every ip_day.

  • boebooleanOptional

    Default false

    true adds boe beside oil, gas and water in every forecast that has streams, computed when read, so older plans have it too. Absent, empty or false: no boe key anywhere.

    BOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.

    Its P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in wells. On totals, and with include=wells on each well's forecasts; with band_eur, totals[].eur.boe adds p10 and p90. Anything else is a 400.

  • normalize_lateral_ftnumberOptional

    ≥ 100, ≤ 20000

    With sort (ignored without it, as design and ip_day are): scale each well's metric to this lateral length before sorting, × normalize_lateral_ft / its lateral_length_ft, so 1000 ranks wells per 1,000 ft of lateral; value is then the scaled one. 100 to 20,000.

  • model_setstringOptional

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

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

    • model_set=default reaches the base dataset; once the server retires it, a 400 naming the set answering instead.
    • An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in details.allowed (published sets only once default is retired); a set that can't load, a 503 with the reason.
    • Plans and exports stay in their set: a call naming them (by path, plan, ids, source.plan, a scenario's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; naming resources of two sets in one request is a 400.

Responses

200 OK

The plan.

  • idstringRequired

    Format uuid

    Plan id.

  • namestring or nullRequired

    Plan name.

  • statusstringRequired

    running, then done or error.

    "running""done""error"
  • pdpbooleanRequired

    Whether existing wells are in spacing.

  • totalintegerRequired

    Wells.

  • doneintegerRequired

    Wells finished; with per_well_errors, a well that could not be placed counts as finished.

  • progressnumberRequired

    ≥ 0, ≤ 1

    Share of the work done: wells weighted by the worker steps (spacing, spacing features, forecast) their chunks have finished; with per_well_errors, a well that could not be placed counts as finished.

  • created_atstringRequired

    Format date-time

    Start time.

  • secondsnumberRequired

    Run time so far, or in total once finished.

  • designsarray of objectsRequired

    The completion designs every well runs with.

    ShowHide 12 child fields in each item
    • indexintegerRequired

      ≥ 0

      Position in designs.

    • namestringRequired

      Name.

    • inputsobjectRequired

      As requested, blanks as null; the stage fields only where the set's models read them.

      ShowHide 5 child fields
      • fluid_bbl_per_ftnumber or nullRequired

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

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

    • fluid_bbl_per_ftnumberRequired

      Fluid used, bbl/ft.

    • proppant_lb_per_ftnumberRequired

      Proppant used, lb/ft.

    • completions_sourcestringRequired

      input when both were entered, otherwise how the defaults were made.

    • formationsarray of objectsRequired

      Every formation the request's wells or the design name; wells without a formation use the design's own values.

      ShowHide 9 child fields in each item
      • formationstringRequired

        Formation.

      • inputsobjectRequired

        As requested, blanks as null; the stage fields only where the set's models read them.

        ShowHide 5 child fields
        • fluid_bbl_per_ftnumber or nullRequired

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

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

      • fluid_bbl_per_ftnumberRequired

        Fluid used, bbl/ft.

      • proppant_lb_per_ftnumberRequired

        Proppant used, lb/ft.

      • completions_sourcestringRequired

        input when both were entered, otherwise how the defaults were made.

      • stage_length_ftnumberOptional

        Stage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

      • clusters_per_stagenumberOptional

        Clusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

      • frac_rate_bbl_per_minnumberOptional

        Frac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

      • sourcesobjectOptional

        How each stage value used was found: input when the request set it, else the median's text.

        ShowHide 3 child fields
        • stage_length_ftstringOptional

          input, or how the default was made.

        • clusters_per_stagestringOptional

          input, or how the default was made.

        • frac_rate_bbl_per_minstringOptional

          input, or how the default was made.

    • stage_length_ftnumberOptional

      Stage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

    • clusters_per_stagenumberOptional

      Clusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

    • frac_rate_bbl_per_minnumberOptional

      Frac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

    • sourcesobjectOptional

      How each stage value used was found: input when the request set it, else the median's text.

      ShowHide 3 child fields
      • stage_length_ftstringOptional

        input, or how the default was made.

      • clusters_per_stagestringOptional

        input, or how the default was made.

      • frac_rate_bbl_per_minstringOptional

        input, or how the default was made.

    • unusedarray of stringsOptional

      The stage fields the request sent, on the design or any narrower layer, that the model set's models don't read, so nothing used them; only when there is one.

      "stage_length_ft""clusters_per_stage""frac_rate_bbl_per_min"
  • errorobject or nullRequired

    Why the plan failed.

    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.

  • totalsarray of objects or nullRequired

    Totals per design, once done. On a plan made with scenarios, one per scenario and design, scenario by scenario in the order of scenarios, each with its scenario: there totals[d] is not design d.

    ShowHide 8 child fields in each item
    • designintegerRequired

      ≥ 0

      The design, as its index in designs.

    • wells_with_forecastintegerRequired

      Wells with a forecast.

    • wells_flaggedinteger or nullRequired

      Wells whose checks flagged inputs outside training; null when no well's inputs could be checked. A well whose only finding is context (neighbors' production outside training) isn't counted. When wells_flagged is above 0, show the flag beside any total you quote, saying how many wells it covers.

    • forecastobjectRequired

      Cumulative oil (bbl), gas (mcf) and water (bbl) by ip_day, or why the well has no forecast (no formation).

      ShowHide 2 variants

      One of

      • Forecasts per stream object

        Forecasts per stream. A v2 forecast carries the streams its model set serves (GET /model-sets streams), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan streams) carries only those.

        • oilobjectOptional

          One stream's forecast: cumulative volume at each ip_day, or why it couldn't run.

          ShowHide 2 variants

          One of

          • A forecast stream object

            A forecast stream.

            • model_numstringRequired

              Model that produced the forecast.

            • targetstringRequired

              Model target column, as novi_oil.

            • unitstringRequired

              Volume unit: bbl for oil and water, mcf for gas.

              "bbl""mcf"
            • ip_daysarray of integersRequired

              ip_days with a forecast, ascending.

            • valuesarray of numbersRequired

              Cumulative volumes, one per ip_day.

            • missingarray of stringsRequired

              Model features that were blank for this well and fell back to the model's own handling.

            • eurobjectOptional

              With eur: true, on oil and gas, and on water with eur_water: true: the EUR, fit on every ip_day of the forecast (before any ip_days filter).

              ShowHide 2 variants

              One of

              • An EUR object

                An EUR.

                • valuenumberRequired

                  Cumulative volume at days: the forecast to its last ip_day, then the decline curve (bbl for oil, mcf for gas).

                • daysintegerRequired

                  ip_day the EUR is at: the last 30-day step within eur_years.

                • arpsobjectRequired

                  The modified Arps curve fitted to the extension, not to the 3-year forecast itself.

                  ShowHide 4 child fields
                  • q_inumber or nullRequired

                    Initial rate of the extension fit, per day (0 for a dry well).

                  • dnumber or nullRequired

                    Nominal decline of the extension fit, per day.

                  • bnumber or nullRequired

                    Hyperbolic exponent of the extension fit.

                  • terminal_yearnumber or nullRequired

                    Year the curve switches to terminal (exponential) decline.

                • curveobjectOptional

                  With eur_curve: the cumulative from the forecast's last ip_day to days.

                  ShowHide 2 variants

                  One of

                  • The curve object

                    The curve.

                    • step_daysintegerRequired

                      30 for month, 360 for year.

                      30360
                    • ip_daysarray of integersRequired

                      From the forecast's last ip_day plus one step to the EUR's days, ascending: every 30 days (month), or every 360 days and the EUR's days last (year).

                    • valuesarray of numbersRequired

                      Cumulative volumes to 0.01, one per ip_day, continuing the forecast's values; the last is the EUR's value to 0.01.

                  • No curve object

                    No curve.

                    • errorstringRequired

                      Why there is no curve: the decline fit returned no extension, the forecast worker failed to fit one again (POST /forecasts), or the extension doesn't end on this EUR at its day on the forecast's month grid.

              • No EUR object

                No EUR.

                • errorstringRequired

                  Why there is no EUR, as the decline fit reports it.

            • bandsobjectOptional

              With bands: true: the P10 (low) and P90 (high) cumulative curves on these ip_days, or why this stream has none.

              ShowHide 2 variants

              One of

              • Option 1 object

                Bands: Novi's predrill bands (split conformal, safe variant), the conformal P10 (low) and P90 (high) at each ip_day around this forecast, stabilized from their rates so each stays cumulative. They usually bracket the forecast but aren't guaranteed to.

                • p10objectRequired

                  The low curve (P10 in Novi's convention): the conformal lower bound at each ip_day, stabilized. Usually below the forecast, but not always: it is rebuilt from non-negative rates, so it can sit above the forecast where the forecast's cumulative dips.

                  ShowHide 2 child fields
                  • valuesarray of numbersRequired

                    The band's cumulative volumes, one per ip_day of the stream.

                  • eurobjectOptional

                    With band_eur: true, on oil and gas, and on water with eur_water: true: this band's EUR, fit like the forecast's (every ip_day, the same decline settings).

                    Same fields as Eur.

                • p90objectRequired

                  The high curve (P90 in Novi's convention): the conformal upper bound at each ip_day, stabilized. Usually above the forecast, but not guaranteed to be.

                  Same fields as Band.

              • No bands object

                No bands.

                • errorstringRequired

                  Why this stream has no bands.

          • A stream that failed object

            A stream that failed.

            • errorstringRequired

              Why this stream has no forecast.

        • gasobjectOptional

          One stream's forecast: cumulative volume at each ip_day, or why it couldn't run.

          Same fields as StreamForecast.

        • waterobjectOptional

          One stream's forecast: cumulative volume at each ip_day, or why it couldn't run.

          Same fields as StreamForecast.

        • boeobjectOptional

          With boe: true: the forecast's BOE beside its streams, or why it has none.

          BOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.

          Its P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in wells.

          ShowHide 2 variants

          One of

          • BOE object

            BOE.

            • unitstringRequired

              Always BOE.

              "BOE"
            • ip_daysarray of integersRequired

              Oil's ip_days (with ip_days, only those asked for).

            • valuesarray of numbersRequired

              BOE cumulative volumes, one per ip_day.

            • wellsintegerOptional

              ≥ 1

              On totals only: the wells summed, those whose own BOE is ok (both an oil and a gas forecast on the same ip_days). Oil's and gas's own totals may cover more wells.

            • eurobjectOptional

              On a well's forecast with eur: true: oil's EUR plus gas's / 6. Totals have none: their BOE EUR is in totals[].eur.boe.

              ShowHide 2 variants

              One of

              • A BOE EUR object

                A BOE EUR.

                • valuenumberRequired

                  Oil EUR plus gas EUR / 6, to 0.1.

                • daysintegerRequired

                  The later of oil's and gas's EUR days.

                • curveobjectOptional

                  With eur_curve, when oil's and gas's EURs both have curves: BOE's cumulative curve, or why there is none.

                  ShowHide 2 variants

                  One of

                  • The BOE curve object

                    The BOE curve.

                    • step_daysintegerRequired

                      The streams' curve step: 30 for month, 360 for year.

                      30360
                    • ip_daysarray of integersRequired

                      The union of oil's and gas's curve ip_days, ascending: each stream's steps and its own EUR day, so the shorter stream's EUR day can fall between two steps.

                    • valuesarray of numbersRequired

                      Oil's cumulative plus gas's / 6 at each ip_day, to 0.01: each stream linear between its curve points from its forecast's last value, and held at its EUR after its last point. The last is at the later EUR day: a stream whose curve ends there gives its last curve value (to 0.01), and one whose curve ended sooner its EUR, so it may differ from value in its last digit, as value is to 0.1.

                  • No BOE curve object

                    No BOE curve.

                    • errorstringRequired

                      Why there is no BOE curve: oil's or gas's curve failed or is missing, named, oil before gas.

              • No BOE EUR object

                No BOE EUR.

                • errorstringRequired

                  Why there is no BOE EUR: oil's or gas's EUR failed, named, oil before gas.

            • bandsobjectOptional

              With bands: true: BOE's P10 and P90, or why it has none. On totals, summed over the wells summed when every one has BOE bands.

              ShowHide 2 variants

              One of

              • BOE bands object

                BOE bands.

                • p10objectRequired

                  The low curve: oil's P10 plus gas's P10 / 6.

                  ShowHide 2 child fields
                  • valuesarray of numbersRequired

                    One per ip_day of the BOE.

                  • eurobjectOptional

                    With band_eur: true: this band's oil EUR plus gas EUR / 6.

                    Same fields as BoeEur.

                • p90objectRequired

                  The high curve: oil's P90 plus gas's P90 / 6.

                  Same fields as BoeBand.

              • No BOE bands object

                No BOE bands.

                • errorstringRequired

                  Why there are none: oil's or gas's bands failed (named, oil before gas), or on totals some wells summed have none.

          • No BOE object

            No BOE.

            • errorstringRequired

              Why there is no BOE: a stream failed (named, oil before gas), oil and gas are on different ip_days, or on totals no well has both.

      • No forecast object

        No forecast.

        • errorstringRequired

          Why the well has no forecast.

    • scenariostringOptional

      On a plan made with scenarios: the scenario these wells are in. Scenarios are alternatives, so no total adds two.

    • wells_contextintegerOptional

      ≥ 1

      Wells whose checks list neighbors' production outside training in context, flagged or not; absent when none.

    • eurobjectOptional

      With eur: true, each stream's EUR summed over the wells with one, and BOE over the wells with both. A v2 forecast carries the streams its model set serves (GET /model-sets streams), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan streams) carries only those.

      ShowHide 4 child fields
      • boeobjectRequired

        BOE EUR over the wells with both fits, so the sum and the well count agree.

        ShowHide 4 child fields
        • valuenumber or nullRequired

          Oil EUR plus gas EUR / 6 (bbl of oil equivalent) summed over the wells with both; null when none has.

        • wellsintegerRequired

          Wells with both an oil and a gas EUR.

        • p10objectOptional

          With boe and band_eur: each well's P10 oil EUR plus P10 gas EUR / 6, summed over the wells with both.

          ShowHide 2 child fields
          • valuenumber or nullRequired

            This band's EUR summed over the wells with one; null when none has.

          • wellsintegerRequired

            Wells with this band's EUR.

        • p90objectOptional

          With boe and band_eur: each well's P90 oil EUR plus P90 gas EUR / 6, summed over the wells with both.

          Same fields as BandEurTotal.

      • oilobjectOptional

        A stream's EUR over the plan.

        ShowHide 5 child fields
        • valuenumber or nullRequired

          EUR summed over the wells with one; null when none has.

        • daysinteger or nullRequired

          ip_day of the EUR; null when none has one, or when the wells summed differ in eur_years: the sum then runs to no one day, and each scenario is read apart.

        • wellsintegerRequired

          Wells with an EUR.

        • p10objectOptional

          With band_eur: true, the P10 band's EUR over the plan.

          Same fields as BandEurTotal.

        • p90objectOptional

          With band_eur: true, the P90 band's EUR over the plan.

          Same fields as BandEurTotal.

      • gasobjectOptional

        A stream's EUR over the plan.

        Same fields as EurTotal.

      • waterobjectOptional

        Only with eur_water: true. BOE doesn't read it.

        Same fields as EurTotal.

    • by_dateobjectOptional

      When any well has a TIL date, from any layer: its streams summed by calendar date.

      ShowHide 3 child fields
      • datesarray of stringsRequired

        Month starts from the earliest TIL date's month through the first one on or after the latest TIL date plus horizon_days.

      • horizon_daysintegerRequired

        The forecast horizon the dates run past the latest TIL: 1,080 days.

      • forecastobjectRequired

        Per stream. A v2 forecast carries the streams its model set serves (GET /model-sets streams), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan streams) carries only those.

        ShowHide 3 child fields
        • oilobjectOptional

          One stream's plan total by date, or why there is none.

          ShowHide 2 variants

          One of

          • Cumulative volumes by date object

            Cumulative volumes by date.

            • valuesarray of numbersRequired

              One per date.

            • bandsobjectOptional

              With bands: true, the wells' P10s and P90s by date the same way, when every well has them: a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.

              ShowHide 2 child fields
              • p10array of numbersRequired

                One per date.

              • p90array of numbersRequired

                One per date.

          • No total object

            No total.

            • errorstringRequired

              Why this stream has no total (no well has its forecast).

        • gasobjectOptional

          One stream's plan total by date, or why there is none.

          Same fields as ByDateStream.

        • waterobjectOptional

          One stream's plan total by date, or why there is none.

          Same fields as ByDateStream.

Show all 33 fields
  • linksobjectRequired

    Related URLs.

    ShowHide 3 child fields
    • selfstringRequired

      This plan.

    • wellsstringRequired

      This plan with its wells.

    • exportstringOptional

      The zip export; absent on a Legacy Forecast (origin.engine fe): export it with POST /exports.

  • storageobject or nullOptional

    Only with include=storage or on updatePlan. Null without a state store.

    ShowHide 7 child fields
    • tenantstringRequired

      Owning tenant.

    • savedbooleanRequired

      Kept until deleted when true.

    • expires_atstring or nullRequired

      Format date-time

      Scratch expiry, null when saved.

    • created_atstringRequired

      Format date-time

      Creation time.

    • updated_atstringRequired

      Format date-time

      Last metadata update.

    • created_bystring or nullRequired

      The email of the user who posted the plan, as created_by on saved documents. Null for older plans.

    • sharesintegerRequired

      ≥ 0

      Active, unrevoked and unexpired share count.

  • requestobject or nullOptional

    Only with include=request: the body POST /plans accepted, keys as sent after an assumption set's fill, without callback_url and dry_run. A field sent as null comes back null unless the set filled it; a plan made with from_plan carries its source plan's body. Null for an older plan, one made through the legacy POST /api/plan, or one re-run from either.

    ShowHide 21 child fields
    • wellsarray of objectsOptional

      1 to 100000 items

      Plan wells (required unless layout or layouts is sent); up to the server's GET /dataset limits.plan_wells (10,000 by default, at most 100,000) divided by the number of designs.

      ShowHide 22 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].

      • lateral_outsidestring or nullOptional

        Ignored; accepted so POST /layouts/fill wells with lateral_check can be sent as they are.

        "above""below"
      • 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: the lateral runs from heel, else shl, to bhl, unless typed_lateral applies. Accepted so POST /layouts/fill wells can be sent as they are.

      • til_datestring or nullOptional

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

      • partinteger or nullOptional

        Ignored, as is bench: accepted so POST /layouts/fill wells can be sent as they are.

      Show all 22 fields
      • benchinteger or nullOptional

        Ignored.

      • 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

        The alternative the well is in: a scenario's wells space against only each other and existing wells, never another scenario's. A name of 1 to 60 characters, trimmed.

        Equal names (exact, case-sensitive) are one scenario; with pdp false its wells space against only each other. Give every well a scenario, or none (400 at the first without one). At most 10 scenarios on POST /forecasts, each its own spacing run, and 20 on POST /plans (400 at the first well past it, with details.max and details.count). Designs and pdp apply to every scenario unless scenarios sets its own.

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

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

      • namestring or nullOptional

        up to 60 characters

        Your name for the well, 1 to 60 characters once trimmed, on POST /plans, POST /forecasts and POST /inventories/write; other routes that take wells answer 400. null is none; a blank name is a 400.

        Names needn't be unique. Reads show it beside label, which stays Plan well N (Drawn well N on POST /forecasts). A plan's export tables put it in their well column, keeping their row order, with a leading quote where a spreadsheet would read it as a formula. ARIES heads the well with it, unquoted, and sorts by header, so wells with one name share a header: send aries.well_key: id to keep them apart.

    • layoutobjectOptional

      Instead of wells: a fill boundary the server lays the plan's wells out in, up to GET /dataset limits.plan_wells divided by the number of designs and at most 10,000, a fill's own limit.

      ShowHide 22 child fields

      Send exactly one of: area or polygon.

      Send exactly one of: spacing_ft and formation or benches.

      • polygonarray of [number, number]sOptional

        3 to 500 items

        Area corners, in order (closing point optional). Edges that cross are a 400.

      • azimuth_degnumberOptional

        Default 0≥ -360, ≤ 360

        Direction wells are drilled, degrees clockwise from north.

      • spacing_ftnumberOptional

        ≥ 100, ≤ 10000

        Distance between wells, ft.

      • lateral_length_ftnumber or nullOptional

        ≥ 1000, ≤ 30000

        Lateral length, ft; null or absent runs each well edge to edge.

      • setback_ftnumber or nullOptional

        Default 0≥ 0, ≤ 2640

        Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).

      • areaobjectOptional

        Instead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is).

        ShowHide 2 variants

        One of

        • A polygon object

          A polygon.

          • typeanyRequired

            Always "Polygon"

            One part.

          • coordinatesarray of arraysRequired

            at least 1 itemsItems at least 3 items

            The outer ring, then its holes.

        • A multipolygon object

          A multipolygon.

          • typeanyRequired

            Always "MultiPolygon"

            Several parts, taken together.

          • coordinatesarray of arraysRequired

            at least 1 itemsItems at least 1 items

            The parts.

      • setback_end_ftnumber or nullOptional

        ≥ 0, ≤ 2640

        Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.

      • min_lateral_ftnumber or nullOptional

        ≥ 1000, ≤ 30000

        Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.

        A kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.

      • standoff_ftnumber or nullOptional

        ≥ 0, ≤ 5280

        Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.

      • wells_per_padinteger or nullOptional

        ≥ 1, ≤ 50

        Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.

        A fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's wells with pads. POST /plans keeps pad keys: with layout, the 1-based pad number as text; with layouts, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo pads) as a plan scenario's wells in POST /economics.

      • benchesarray of objectsOptional

        1 to 10 items

        Instead of spacing_ft: benches laid out together, each landed in its own formation, at its own tvd_ft, landing_below_top_ft or landing_fraction. Not with the layout's formation, tvd_ft, landing_below_top_ft or landing_fraction.

        ShowHide 13 child fields in each item

        Send exactly one of: spacing_ft or wells_per_section.

        • formationstringRequired

          The bench's formation (case-insensitive): its wells land in it, and standoff_ft stands off its laterals.

        • spacing_ftnumberOptional

          ≥ 100, ≤ 10000

          Distance between the bench's wells, ft. Not with wells_per_section.

        • wells_per_sectionnumberOptional

          ≥ 0.528, ≤ 52.8

          Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).

        • offset_ftnumber or nullOptional

          Default 0≥ -10000, ≤ 10000

          Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.

          Lines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.

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

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

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          Fluid in bbl per lateral ft for the bench's wells: over the layout's, echoed as layer pad_formation. Needs one design, or none.

        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          Proppant in lb per lateral ft for the bench'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.

        • declineobjectOptional

          EUR settings for the bench's wells, as layer pad_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.

      • formationstringOptional

        Target formation every laid-out well lands in (case-insensitive; GET /formations lists them). Required without benches; not with them.

      Show all 22 fields
      • 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).

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

      • til_datestringOptional

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

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        Fluid in bbl per lateral ft for the layout's wells: below a bench's and above a scenario's and the design's, echoed as layer pad. Works with benches. Needs one design, or none. A layout alone echoes no til_date or landing in inputs.resolved; completions here turn on its completion keys.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        Proppant in lb per lateral ft for the layout'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.

      • declineobjectOptional

        EUR settings for the layout's wells, as layer 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.

    • layoutsarray of objectsOptional

      1 to 100 items

      Instead of wells or layout: layouts whose wells the plan takes one after another, up to GET /dataset limits.plan_wells divided by the number of designs in all, each at most 10,000 (a fill's own limit).

      • All layouts share one work limit (about a second). Each evens out as POST /layouts/fill does, with the work the plan's fills leave, unless any layout has a bench with a non-zero offset_ft: then none does, so a stagger set across layouts holds.
      • Errors name layouts[i]. Past the plan's wells in all: a 400 on layouts[i] with details.max (the plan's wells), details.before (wells the layouts before it laid out) and details.count (its own).
      ShowHide 23 child fields in each item

      Send exactly one of: area or polygon.

      Send exactly one of: spacing_ft and formation or benches.

      • polygonarray of [number, number]sOptional

        3 to 500 items

        Area corners, in order (closing point optional). Edges that cross are a 400.

      • azimuth_degnumberOptional

        Default 0≥ -360, ≤ 360

        Direction wells are drilled, degrees clockwise from north.

      • spacing_ftnumberOptional

        ≥ 100, ≤ 10000

        Distance between wells, ft.

      • lateral_length_ftnumber or nullOptional

        ≥ 1000, ≤ 30000

        Lateral length, ft; null or absent runs each well edge to edge.

      • setback_ftnumber or nullOptional

        Default 0≥ 0, ≤ 2640

        Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).

      • areaobjectOptional

        Instead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is).

        Same fields as UnitArea.

      • setback_end_ftnumber or nullOptional

        ≥ 0, ≤ 2640

        Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.

      • min_lateral_ftnumber or nullOptional

        ≥ 1000, ≤ 30000

        Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.

        A kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.

      • standoff_ftnumber or nullOptional

        ≥ 0, ≤ 5280

        Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.

      • wells_per_padinteger or nullOptional

        ≥ 1, ≤ 50

        Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.

        A fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's wells with pads. POST /plans keeps pad keys: with layout, the 1-based pad number as text; with layouts, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo pads) as a plan scenario's wells in POST /economics.

      • benchesarray of objectsOptional

        1 to 10 items

        Instead of spacing_ft: benches laid out together, each landed in its own formation, at its own tvd_ft, landing_below_top_ft or landing_fraction. Not with the layout's formation, tvd_ft, landing_below_top_ft or landing_fraction.

        ShowHide 13 child fields in each item

        Send exactly one of: spacing_ft or wells_per_section.

        • formationstringRequired

          The bench's formation (case-insensitive): its wells land in it, and standoff_ft stands off its laterals.

        • spacing_ftnumberOptional

          ≥ 100, ≤ 10000

          Distance between the bench's wells, ft. Not with wells_per_section.

        • wells_per_sectionnumberOptional

          ≥ 0.528, ≤ 52.8

          Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).

        • offset_ftnumber or nullOptional

          Default 0≥ -10000, ≤ 10000

          Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.

          Lines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.

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

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

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          Fluid in bbl per lateral ft for the bench's wells: over the layout's, echoed as layer pad_formation. Needs one design, or none.

        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          Proppant in lb per lateral ft for the bench'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.

        • declineobjectOptional

          EUR settings for the bench's wells, as layer pad_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.

      • formationstringOptional

        Target formation every laid-out well lands in (case-insensitive; GET /formations lists them). Required without benches; not with them.

      Show all 23 fields
      • 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).

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

      • til_datestringOptional

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

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        Fluid in bbl per lateral ft for the layout's wells: below a bench's and above a scenario's and the design's, echoed as layer pad. Works with benches. Needs one design, or none. A layout alone echoes no til_date or landing in inputs.resolved; completions here turn on its completion keys.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        Proppant in lb per lateral ft for the layout'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.

      • declineobjectOptional

        EUR settings for the layout's wells, as layer 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.

      • scenariostringOptional

        1 to 60 characters

        Every one of the layout's wells' scenario: send one on every layout, or on none. Layouts may share one, a development across units.

    • 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, layout or layouts.

      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.

    • pdpbooleanOptional

      Default true

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

    • namestring or nullOptional

      up to 100 characters

      Your name for the plan.

    • eurbooleanOptional

      Default false

      Add the EUR (Novi type-curve decline fit) to each oil and gas forecast; GET /dataset eur says whether this server has it (503 if not).

    • 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. Needs eur: true (a 400 on eur_water without it).

    • declineobjectOptional

      Decline fit settings, with eur: true only; any left out take Novi's defaults (GET /dataset eur.defaults), and oil and gas (with eur_water, water) override them per stream. The plan layer: a well, pad, layout, bench, scenario or formations entry can set its wells' own, field by field.

      Same fields as DeclineSettings.

    Show all 21 fields
    • til_datestringOptional

      Format date

      TIL (first production) date, YYYY-MM-DD, for every well no narrower layer dates: from GET /dataset as_of to 30 years from today. Echoed in each such well's inputs.

    • bandsbooleanOptional

      Default false

      Add P10/P90 bands to each stream forecast (Novi's predrill bands, same model call); GET /dataset bands says which streams have them, and a request answers 503 when none has.

    • band_eurbooleanOptional

      Default false

      Also fit each oil and gas band to an EUR with the decline settings, and water's with eur_water: two more decline fits per such forecast (about three times eur's fitting). Needs bands and eur.

    • callback_urlstring or nullOptional

      up to 2048 characters

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

    • depletion_chainbooleanOptional

      Feed each planned well's P50 production to the plan wells it is a parent of, those with a later TIL month. On by default where GET /dataset depletion_chain.available is true, else off. Only plans take it.

      • A well whose planned parent is TIL in an earlier calendar month is re-forecast after it, wave by wave, each design on its own parents' P50. A parent read past its 1,080-day forecast is extended with the plan's decline settings (Novi's defaults without eur).
      • Existing (PDP) parents' production is as GET /dataset depletion_chain.neighbor_production says.
      • false: a planned parent's production reads as 0 in every neighbor-production feature (novi_spacing_sum_prior_* and novi_spacing_delgados_p*), so neighbor production is existing wells' history alone.
      • With available false, the plan runs as without it, and with true sent its echo says why.
      • Each wave adds a production pass and a forecast per design, so deep chains take longer. steps.chain counts the waves' passes running, and a chained well finishes once its last design's wave lands.
    • dry_runbooleanOptional

      Default false

      With true, only check and count: the same checks as a create and a 200 with PlanDryRun, with nothing started (no job, no callback). false or absent: a plan.

      An Idempotency-Key is neither kept nor replayed. Wells aren't placed, so a well whose TVD can't be estimated or whose landing can't be placed answers 200 here and fails once the plan runs (only that well with per_well_errors: true, unless no well can be placed).

    • per_well_errorsbooleanOptional

      Default false

      With true, a well whose TVD or landing can't be placed fails alone; the plan ends in error only when no well can be placed. Without it, one placement failure fails the whole plan.

      • The plan lists failed_wells. The well's summary has error {field, message}, error forecasts and no estimates or spacing; reading it or its explanations is a 409. Stats count it as missing; exports keep its reason with blank placement columns.
      • Its plan neighbors are spaced and forecast without it, as if it were never drilled: less interference, so their forecasts may read high.
      • For the like-for-like plan, run the wells again with this one placed: tvd_ft for its landing_fraction or landing_below_top_ft, and a target formation if it has none (a plan built from a layout goes as its well list, so only this well changes).
      • Economics leaves any scenario holding it unpriced (economics null, reason naming the first well without flows); list the placed wells in plan.wells to price them.
      • Worker or internal errors still fail the plan.
    • from_planstringOptional

      Format uuid

      Instead of wells, layout or layouts: a done plan's id. The new plan runs its stored request again on the model set's current models, and echoes from_plan.

      • It keeps the wells where they were (a layout's aren't laid out again), designs, pdp, decline and EUR settings, bands, depletion chain, per_well_errors and its start day, which undated wells take.
      • Only name, callback_url and dry_run go with it; any other field is a 400 naming it. A plan you can't see on this model set is 404; one running or failed is 409.
      • POST /comparisons of the two names the release and model set each ran on, so a difference comes from the models or the release, not the inputs.
    • assumption_setobjectOptional

      A saved assumption set: each plan field it holds that this body leaves out or sends as null is filled from it before the body is checked, unless clear names it; a field the body sends wins.

      • It fills designs, formations, til_date, pdp, depletion_chain, eur, eur_water, decline, bands and band_eur, never its pad_template or economics (not plan fields). A 400 on a filled field names it and starts "From assumption set {name} (version {n}):".
      • A set you can't read is 404; one made on another model set, a 400 on assumption_set naming both; without a state store, 409; with from_plan, 400.
      • The plan echoes assumption_set with the version run and the fields filled; GET /plans/{id}?include=request answers the body after the fill.
      • Without one, a plan runs on the dataset's defaults (Novi defaults) and has no assumption_set echo.
      ShowHide 3 child fields
      • idstringRequired

        Format uuid

        An assumption set's id, from POST /saved/assumption-sets.

      • versionintegerOptional

        ≥ 1

        The version you read; another one is a 409 whose details.version is the current one. Left out, the current version.

      • cleararray of strings or nullOptional

        Set values the fill skips: til_date, eur or both. Absent, null or []: the set fills as without it.

        • til_date: the set's start date, so wells this body doesn't date run undated.
        • eur: the set's eur, eur_water, decline and band_eur, and each filled formations entry's decline, so the plan runs without EUR; bands and those entries' landings still fill.
        • A field this body sends still wins: a til_date sent beside it runs on that date, and "eur": true runs EUR on this body's own settings.
        • A name the set doesn't hold is ignored, so you needn't read the set first; a name may repeat. Any other value is a 400 on assumption_set.clear.
        • assumption_set.filled leaves out what the set didn't fill.
        "til_date""eur"
  • from_planstringOptional

    Format uuid

    Only on a plan made with from_plan: the plan whose stored request this one ran again.

  • assumption_setobjectOptional

    Only on a plan made with assumption_set, or with from_plan from one: the set it ran with.

    ShowHide 4 child fields
    • idstringRequired

      Format uuid

      The set's id.

    • versionintegerRequired

      ≥ 1

      The version the plan ran with.

    • namestringRequired

      The set's name then.

    • filledarray of stringsRequired

      The request fields the set filled, in the set's key order. A value they set reads in each well's resolved inputs as the field it filled (plan or plan_formation).

  • failed_wellsobjectOptional

    Present with per_well_errors, including while running and on error; a failed well's plan neighbors are spaced and forecast without it.

    ShowHide 2 child fields
    • countintegerRequired

      Every well that could not be placed.

    • wellsarray of objectsRequired

      up to 100 items

      First failed wells, lowest index first.

      ShowHide 3 child fields in each item
      • indexintegerRequired

        Plan well index.

      • fieldstringRequired

        Placement field.

        "tvd_ft""landing_below_top_ft""landing_fraction""formation"
      • messagestringRequired

        Why the well could not be placed.

  • stepsobjectOptional

    While running: chunks (up to 1,000 wells) in each worker step now.

    ShowHide 5 child fields
    • spacingintegerRequired

      Chunks in spacing.

    • calcintegerRequired

      Chunks in the spacing feature step.

    • forecastintegerRequired

      Chunks in forecast.

    • eurintegerOptional

      With eur: true, chunks fitting EUR.

    • chainintegerOptional

      With depletion_chain applied: wave passes running (one design's production pass and re-forecast for up to 1,000 wells).

  • scenariosarray of objectsOptional

    When the request sent scenarios: each, in the order its first well came, with its well count.

    ShowHide 3 child fields in each item
    • namestringRequired

      The scenario.

    • wellsintegerRequired

      ≥ 1

      Its wells.

    • pdpbooleanOptional

      The scenario's own pdp; only when scenarios set one. Without it the scenario ran with the request's pdp.

  • layoutobjectOptional

    When the request sent layout: what was laid out.

    ShowHide 14 child fields
    • countintegerRequired

      Wells.

    • azimuth_degnumberRequired

      Azimuth used.

    • lateral_length_ftnumber or nullRequired

      Length used, or null for edge to edge.

    • spacing_ftnumberOptional

      Spacing used; left out with benches.

    • setback_ftnumberOptional

      Setback used, ft; only when the request sent one.

    • setback_end_ftnumberOptional

      End setback used, ft; only when sent.

    • min_lateral_ftnumberOptional

      Shortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out.

    • standoff_ftnumberOptional

      Standoff used, ft; only when sent.

    • standoff_wellsintegerOptional

      ≥ 0

      With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.

    • wells_per_padintegerOptional

      Wells per pad; only when sent.

    • wells_per_sectionnumberOptional

      With benches: their wells_per_section added up, the unit's total.

    • padsarray of arraysOptional

      With wells_per_pad: each pad's wells, as indexes of the response's (or plan's) wells.

    • benchesarray of objectsOptional

      With benches: each bench as laid out.

      ShowHide 6 child fields in each item
      • spacing_ftnumberRequired

        Spacing used, ft.

      • wells_per_sectionnumberRequired

        5,280 ft / spacing_ft, or as sent.

      • offset_ftnumberRequired

        Offset used, ft.

      • formationstring or nullRequired

        The bench's formation, or null when none was sent.

      • countintegerRequired

        ≥ 0

        Wells in the bench.

      • wellsarray of integersRequired

        Items ≥ 0

        The bench's wells, as indexes of the response's (or plan's) wells.

    • formationstringOptional

      The formation every well landed in, as GET /formations names it; left out with benches, which name their own.

  • layoutsarray of objectsOptional

    When the request sent layouts: what each laid out, in order.

    ShowHide 16 child fields in each item
    • firstintegerRequired

      ≥ 0

      The plan index of the layout's first well; its wells follow in order.

    • countintegerRequired

      Wells.

    • azimuth_degnumberRequired

      Azimuth used.

    • lateral_length_ftnumber or nullRequired

      Length used, or null for edge to edge.

    • scenariostringOptional

      When the layout was sent with one: its scenario.

    • spacing_ftnumberOptional

      Spacing used; left out with benches.

    • setback_ftnumberOptional

      Setback used, ft; only when the request sent one.

    • setback_end_ftnumberOptional

      End setback used, ft; only when sent.

    • min_lateral_ftnumberOptional

      Shortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out.

    • standoff_ftnumberOptional

      Standoff used, ft; only when sent.

    • standoff_wellsintegerOptional

      ≥ 0

      With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.

    • wells_per_padintegerOptional

      Wells per pad; only when sent.

    Show all 16 fields
    • wells_per_sectionnumberOptional

      With benches: their wells_per_section added up, the unit's total.

    • padsarray of arraysOptional

      With wells_per_pad: each pad's wells, as indexes of the response's (or plan's) wells.

    • benchesarray of objectsOptional

      With benches: each bench as laid out.

      ShowHide 6 child fields in each item
      • spacing_ftnumberRequired

        Spacing used, ft.

      • wells_per_sectionnumberRequired

        5,280 ft / spacing_ft, or as sent.

      • offset_ftnumberRequired

        Offset used, ft.

      • formationstring or nullRequired

        The bench's formation, or null when none was sent.

      • countintegerRequired

        ≥ 0

        Wells in the bench.

      • wellsarray of integersRequired

        Items ≥ 0

        The bench's wells, as indexes of the response's (or plan's) wells.

    • formationstringOptional

      The formation every well landed in, as GET /formations names it; left out with benches, which name their own.

  • declineobjectOptional

    With eur: true, the plan's decline settings, which a well may override (per_well).

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

    With bands: true, the bands every forecast carries.

    ShowHide 3 child fields
    • percentiles[integer, integer]Required

      The bands' percentiles: 10 (low) and 90 (high).

    • methodstringRequired

      How the bands are made: Novi's predrill bands (split conformal, safe variant).

    • eurbooleanRequired

      Whether each oil and gas band, and water's with eur_water, has its EUR (band_eur).

  • depletion_chainobjectOptional

    With the chain on: depletion_chain true, or absent on a set whose models read neighbors' production. What the chain read and did.

    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.

      Same fields as Decline.

  • callbacksarray of objectsOptional

    up to 1 items

    Only on a plan made with callback_url: its delivery, as an export's callbacks show theirs.

    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.

  • wellsarray of objectsOptional

    With include=wells: the wells, or while running those finished so far.

    ShowHide 14 child fields in each item
    • indexintegerRequired

      ≥ 0

      Position of the well in the request.

    • keystringOptional

      Key the models use for the well, as DRAWN-<index>; other drawn wells appear among neighbors by this key.

    • labelstringOptional

      Display name: Plan well N in a plan, Drawn well N from POST /forecasts, counting from 1.

    • inputsobjectOptional

      The well as requested, blanks as null. tvd_ft, landing_below_top_ft, landing_fraction and til_date show a layer's value when the well took one.

      ShowHide 16 child fields
      • 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 nullRequired

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

      • tvd_ftnumber or nullRequired

        > 0, < 40000

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

      • landing_below_top_ftnumber or nullRequired

        > -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]Optional

        The heel sent; only when the request sent one.

      • typed_lateralobjectOptional

        The typed_lateral sent; only when the request sent one.

        Same fields as TypedLateral.

      • landing_fractionnumberOptional

        ≥ 0, ≤ 1

        The landing_fraction sent; only when the request sent one.

      • til_datestringOptional

        Format date

        The TIL date the well ran with: its own, else its pad's or layout's, else its scenario's, else the request's til_date. Only when the request sent a date for it; otherwise the well was TIL today.

      • scenariostringOptional

        The well's scenario, only when the request sent scenarios.

      • fluid_bbl_per_ftnumberOptional

        The well's own fluid sent, bbl/ft; only when the request sent one.

      • proppant_lb_per_ftnumberOptional

        The well's own proppant sent, lb/ft; only when the request sent one.

      Show all 16 fields
      • stage_length_ftnumberOptional

        The well's own stage_length_ft sent; only when the request sent one and the set's models read it.

      • clusters_per_stagenumberOptional

        The well's own clusters_per_stage sent; only when the request sent one and the set's models read it.

      • frac_rate_bbl_per_minnumberOptional

        The well's own frac_rate_bbl_per_min sent; only when the request sent one and the set's models read it.

      • resolvedobjectOptional

        What this well was forecast with: its completions once a well, pad, layout or scenario of the request sets one, its TIL date and landing once a pad, scenario or formations entry sets one that a well takes (a layout alone doesn't), and then on every well. Read each key as optional: a later release may send some of these and add others.

        ShowHide 9 child fields
        • fluid_bbl_per_ftobjectOptional

          Fluid used, bbl/ft.

          ShowHide 2 child fields
          • valuenumberRequired

            The value the well was forecast with.

          • layerstringRequired

            The narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's assumption_set.filled lists those fields.

            • well: the well.
            • pad_formation: its pad's formations entry for its formation, or its layout bench.
            • pad: its pads entry, or its layout.
            • scenario_formation: its scenario's formations entry for its formation.
            • scenario: its scenarios entry.
            • plan_formation: the design's entry for its formation, or for a landing the request's formations entry.
            • plan: the design, or the request's til_date.
            • default: nothing set it.
            "well""pad_formation""pad""scenario_formation""scenario""plan_formation""plan""default"
        • proppant_lb_per_ftobjectOptional

          Proppant used, lb/ft.

          Same fields as ResolvedValue.

        • stage_length_ftobjectOptional

          The stage_length_ft used, on a model set whose models read it.

          Same fields as ResolvedValue.

        • clusters_per_stageobjectOptional

          The clusters_per_stage used, on a model set whose models read it.

          Same fields as ResolvedValue.

        • frac_rate_bbl_per_minobjectOptional

          The frac_rate_bbl_per_min used, on a model set whose models read it.

          Same fields as ResolvedValue.

        • completions_sourcestringOptional

          input when a request set both, else how the default was found.

        • til_dateobjectOptional

          A TIL date and the layer it came from.

          ShowHide 2 child fields
          • layerstringRequired

            The narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's assumption_set.filled lists those fields.

            • well: the well.
            • pad_formation: its pad's formations entry for its formation, or its layout bench.
            • pad: its pads entry, or its layout.
            • scenario_formation: its scenario's formations entry for its formation.
            • scenario: its scenarios entry.
            • plan_formation: the design's entry for its formation, or for a landing the request's formations entry.
            • plan: the design, or the request's til_date.
            • default: nothing set it.
            "well""pad_formation""pad""scenario_formation""scenario""plan_formation""plan""default"
          • valuestringOptional

            Format date

            The TIL date the well ran with; left out when no layer set one, and the well ran on the plan's start day, or today in POST /forecasts.

        • landingobjectOptional

          The landing a layer set, and which: one of the three, or none with layer default, when TVD was estimated. estimates.tvd_ft is the TVD the well ran at.

          ShowHide 4 child fields
          • layerstringRequired

            The narrowest layer that set the value. A value an assumption set filled reads as the field it filled (plan or plan_formation), and the plan's assumption_set.filled lists those fields.

            • well: the well.
            • pad_formation: its pad's formations entry for its formation, or its layout bench.
            • pad: its pads entry, or its layout.
            • scenario_formation: its scenario's formations entry for its formation.
            • scenario: its scenarios entry.
            • plan_formation: the design's entry for its formation, or for a landing the request's formations entry.
            • plan: the design, or the request's til_date.
            • default: nothing set it.
            "well""pad_formation""pad""scenario_formation""scenario""plan_formation""plan""default"
          • tvd_ftnumberOptional

            The TVD set, ft.

          • landing_below_top_ftnumberOptional

            The landing below the formation top set, ft.

          • landing_fractionnumberOptional

            The fraction of the formation's thickness set.

        • declineobjectOptional

          The EUR settings this well was fit with, each value with the layer that set it.

          On every well once a well, pad, layout or bench, scenario or formations entry of the request sets one; a plan with no layer below it has no resolved.decline, and its decline echo's flat fields are the base. A stream's value beats its layer's base, and the narrower layer wins first: a well's b_max beats a plan's oil.b_max.

          ShowHide 5 child fields
          • eur_yearsobjectRequired

            Years to EUR, every stream's.

            Same fields as ResolvedValue.

          • oilobjectRequired

            What one stream was fit with, each value with its layer.

            ShowHide 3 child fields
            • terminal_declineobjectRequired

              Terminal decline, as a fraction per year.

              Same fields as ResolvedValue.

            • b_minobjectRequired

              Lowest b.

              Same fields as ResolvedValue.

            • b_maxobjectRequired

              Highest b.

              Same fields as ResolvedValue.

          • gasobjectRequired

            What one stream was fit with, each value with its layer.

            Same fields as ResolvedStreamDecline.

          • waterobjectOptional

            Only with eur_water: true.

            Same fields as ResolvedStreamDecline.

          • baseobjectOptional

            Only with include=decline_base on GET /plans/{id} or GET /plans/{id}/wells/{index}: the flat terminal_decline, b_min and b_max this well ran with, which a stream's value goes over. Left out on older plans.

            • Each layer is the narrowest layer whose flat field set it (plan for the request's flat decline), else default. A value sent on a stream names its layer only on that stream (oil, gas), so compare them to tell the two apart.
            • The depletion chain's water extension reads these settings.
            • Rebuild a plan's own decline from its decline echo, without per_well, not from the plan values here: a plan field every well beats isn't here, and the request's flat pair and each stream's are checked on their own.

            Same fields as ResolvedStreamDecline.

    • lateral_length_ftintegerOptional

      The lateral length the model got, ft, rounded: the well's typed_lateral length when it applies, else from the heel when the well has one, else shl, to bhl.

    • estimatesobjectOptional

      The TVD the models used, entered or estimated.

      ShowHide 2 child fields
      • tvd_ftnumberRequired

        TVD used, ft.

      • tvd_sourcestringRequired

        input, or how it was estimated.

    • forecastsarray of objectsOptional

      One forecast per design, in design order.

      ShowHide 2 variants in each item

      One of

      • Option 1 object

        Forecasts per stream, and the checks of their inputs. A v2 forecast carries the streams its model set serves (GET /model-sets streams), oil, gas and water on a set serving all three; a Legacy Forecast that forecast only some (Plan streams) carries only those.

        • designintegerRequired

          ≥ 0

          The design, as its index in designs.

        • checksobjectRequired

          Inputs the model rarely or never saw in training, or why they weren't checked.

          Every ip_day's row of this design is checked against the oil model's training statistics (on a set without oil, the first served stream's model: gas, else water); the streams share features. An input is out of range only when it is more than 5% of its training 1st to 99th percentile range outside that range. Neighbors' production (parent depletion near the well) is reported in context instead.

          ShowHide 2 variants

          One of

          • Checked inputs object

            Checked inputs.

            • availableanyRequired

              Always true

              The inputs were checked.

            • model_numstringRequired

              Model whose training statistics were used: the oil model, or on a set without oil the first served stream's.

            • flaggedbooleanRequired

              True when out_of_range, missing or unknown_formation reports anything; context doesn't set it. When true, show the flag beside any number you quote from this well and design.

            • out_of_rangearray of objectsRequired

              Numeric inputs outside training in any row, one per feature, in the model's feature order: say each is outside the model's training data, with its value and range.

              Outside means more than 5% of the training range (99th minus 1st percentile) below the 1st or above the 99th percentile of training. A feature whose two percentiles are equal has no margin. The value a feature takes for no such neighbor (days online -1, distances at the spacing defaults) isn't checked, and neighbors' production features are in context.

              ShowHide 5 child fields in each item
              • featurestringRequired

                Model feature, as novi_lateral_length.

              • valuenumberRequired

                The value farthest outside the training range over the rows, in the feature's unit.

              • lownumberRequired

                1st percentile of the feature in training, leaving out the features' no-neighbor value.

              • highnumberRequired

                99th percentile of the feature in training, leaving out the features' no-neighbor value.

              • sidestringRequired

                below low or above high.

                "below""above"
            • missingarray of stringsRequired

              Inputs blank in any row, of those blank in under 5% of training rows (inputs often blank in training aren't listed).

            • unknown_formationstring or nullRequired

              The target formation when the model has no training rows in it, else null.

            • contextarray of objectsOptional

              Neighbors' production features (novi_spacing_sum_prior_, novi_spacing_delgados_p) below the 1st or above the 99th percentile of training in any row, with no margin. They don't set flagged; absent when there are none.

              One per feature, in the model's feature order. They measure the parent depletion near the well: how much nearby parents have produced by its TIL, weighted by how close they are. It moves with where the lateral is drawn more than with completions, and a well drawn today near parents that have produced for years often reads above training. Say the well has more (or less) parent depletion nearby than nearly all training wells, not that an input is unusual.

              Same fields as InputOutOfRange.

          • Inputs not checked object

            Inputs not checked.

            • availableanyRequired

              Always false

              The inputs weren't checked.

            • reasonstringRequired

              Why, as no training statistics for the model.

        • oilobjectOptional

          One stream's forecast: cumulative volume at each ip_day, or why it couldn't run.

          Same fields as StreamForecast.

        • gasobjectOptional

          One stream's forecast: cumulative volume at each ip_day, or why it couldn't run.

          Same fields as StreamForecast.

        • waterobjectOptional

          One stream's forecast: cumulative volume at each ip_day, or why it couldn't run.

          Same fields as StreamForecast.

        • boeobjectOptional

          With boe: true: the forecast's BOE beside its streams, or why it has none.

          BOE is oil plus gas / 6 (6 mcf per bbl), on ip_days where both have a value; on a set serving one of them the other counts 0, and serving neither, BOE is 0.

          Its P10 adds oil's P10 and gas's P10 / 6 (P90 likewise). The models predict each stream apart, so this isn't the P10 of BOE itself; it is as wide as BOE's would be if oil and gas moved together. Novi's P10 is the low case. Totals add the BOE of the wells that have both oil and gas forecasts, and say how many in wells.

          Same fields as BoeForecast.

      • No forecast object

        No forecast.

        • designintegerRequired

          ≥ 0

          The design, as its index in designs.

        • errorstringRequired

          Why the well has no forecast.

    • spacingobjectOptional

      Spacing summary.

      ShowHide 2 child fields
      • nodeobjectRequired

        The drawn well's spacing node.

        ShowHide 4 child fields
        • azimuthnumber or nullRequired

          Lateral azimuth, degrees.

        • heelarray of numbersRequired

          2 items

          Heel [lng, lat]: the surface hole, or estimated from a pad of existing wells within 200 ft.

        • heel_is_virtualbooleanRequired

          Heel estimated rather than drawn.

        • pad_wellsintegerRequired

          Existing wells on the same pad.

      • neighbor_countintegerRequired

        Spacing neighbors.

    • errorobjectOptional

      With per_well_errors, the placement failure.

      ShowHide 2 child fields
      • fieldstringRequired

        Placement field.

        "tvd_ft""landing_below_top_ft""landing_fraction""formation"
      • messagestringRequired

        Why the well could not be placed.

    • valuenumber or nullOptional

      With fields=value and sort: the sort metric's value, rounded to 0.1 in its unit; null for a well without one.

    • checksobject or nullOptional

      Opt-in through fields=checks: the same object as forecasts[design].checks, default design 0; null when none, including failed wells. Show the flag beside any number quoted from a flagged well.

      ShowHide 2 variants

      One of

      • Checked inputs object

        Checked inputs.

        • availableanyRequired

          Always true

          The inputs were checked.

        • model_numstringRequired

          Model whose training statistics were used: the oil model, or on a set without oil the first served stream's.

        • flaggedbooleanRequired

          True when out_of_range, missing or unknown_formation reports anything; context doesn't set it. When true, show the flag beside any number you quote from this well and design.

        • out_of_rangearray of objectsRequired

          Numeric inputs outside training in any row, one per feature, in the model's feature order: say each is outside the model's training data, with its value and range.

          Outside means more than 5% of the training range (99th minus 1st percentile) below the 1st or above the 99th percentile of training. A feature whose two percentiles are equal has no margin. The value a feature takes for no such neighbor (days online -1, distances at the spacing defaults) isn't checked, and neighbors' production features are in context.

          Same fields as InputOutOfRange.

        • missingarray of stringsRequired

          Inputs blank in any row, of those blank in under 5% of training rows (inputs often blank in training aren't listed).

        • unknown_formationstring or nullRequired

          The target formation when the model has no training rows in it, else null.

        • contextarray of objectsOptional

          Neighbors' production features (novi_spacing_sum_prior_, novi_spacing_delgados_p) below the 1st or above the 99th percentile of training in any row, with no margin. They don't set flagged; absent when there are none.

          One per feature, in the model's feature order. They measure the parent depletion near the well: how much nearby parents have produced by its TIL, weighted by how close they are. It moves with where the lateral is drawn more than with completions, and a well drawn today near parents that have produced for years often reads above training. Say the well has more (or less) parent depletion nearby than nearly all training wells, not that an input is unusual.

          Same fields as InputOutOfRange.

      • Inputs not checked object

        Inputs not checked.

        • availableanyRequired

          Always false

          The inputs weren't checked.

        • reasonstringRequired

          Why, as no training statistics for the model.

    • namestringOptional

      The name the request gave the well, trimmed; only when it gave one. label doesn't change. With fields, ask for it by name.

    • nearest_same_formation_ftnumber or nullOptional

      Opt-in through fields=nearest_same_formation_ft: the smallest minxy, ft to 0.1, over the well's spacing neighbours in its own formation.

      The neighbours are the wells, planned or existing, whose lateral midpoints are within the spacing radius of the well (GET /dataset spacing.search_radius_ft). Null when none is, so also when the nearest well in the formation is beyond that radius; when the well has no formation or could not be placed; and on older plans.

    • lateral_length_sourcestringOptional

      Only on a well sent a typed_lateral: typed when the well uses its length_ft, measured when it uses the length between the ends instead. With fields, ask for it by name.

      "typed""measured"
  • next_cursorstring or nullOptional

    With include=wells: cursor for the next page of wells, or while running for the wells that finish next.

  • matchedintegerOptional

    ≥ 0

    With include=wells and a scenario, formation, q or pad that filters: the wells passing them and any wells, finished or not, over every page. A failed plan returns no wells, and no matched.

  • originobjectOptional

    With origin on GET /plans or include=origin, and always on a Legacy Forecast: where the plan came from.

    ShowHide 2 variants

    One of

    • A v2 plan object

      A v2 plan.

      • engineanyRequired

        Always "v2"

        A plan this API ran.

    • A Legacy Forecast object

      A Legacy Forecast.

      • engineanyRequired

        Always "fe"

        A Legacy Forecast, read only. Legacy Forecasts are dynamic imports from Forecast Engine v1.

      • job_idintegerRequired

        The run's job.

      • runstringRequired

        The run's name, as the date it ran and a number.

      • ran_atstringRequired

        Format date-time

        When the run was submitted.

      • indexed_atstringOptional

        Format date-time

        On GET /plans rows: when the server last read the run into its index. A run read again, after its file changed or a read failed, has the later time. created_from keeps a run whose created_at or indexed_at is at or after it.

  • streamsarray of stringsOptional

    With origin: the streams the plan forecast, in oil, gas, water order; its forecasts and totals carry only these. Every stream on a v2 plan.

    "oil""gas""water"
  • stream_labelsobjectOptional

    With origin, only where a stream holds something its name doesn't say: {"oil": "condensate"} on a run that forecast condensate, or on a v2 plan whose model set labels its oil slot condensate.

    ShowHide 1 child field
    • oilstringOptional

      What the oil stream holds, as condensate.

  • timingsobject or nullOptional

    Only with include=timings: where the plan's time went, from each finished chunk (up to 1,000 wells) and depletion chain wave pass. Null when nothing was timed: a queued plan, a Legacy Forecast or an older plan.

    A running plan shows the chunks finished so far, as of its server's last heartbeat (every 30 s by default) when that is another server. A resumed plan counts each finished chunk and pass as the run that finished it timed it, except an older server's.

    ShowHide 2 child fields
    • stepsobjectRequired

      The worker steps with a timed chunk, in this order.

      ShowHide 5 child fields
      • spacingobjectOptional

        The TVD estimate, the subsurface grids and the spacing worker, which run while a chunk holds the spacing step.

        ShowHide 4 child fields
        • chunksintegerRequired

          ≥ 0

          Chunks timed; for chain, wave passes; for wait, both.

        • secondsnumberRequired

          ≥ 0

          Their total, in seconds to 0.01.

        • p50_secondsnumberRequired

          ≥ 0

          The median chunk's seconds, the lower of the two middle ones for an even count.

        • max_secondsnumberRequired

          ≥ 0

          The longest chunk's seconds.

      • calcobjectOptional

        The spacing feature worker.

        Same fields as PlanStepTimes.

      • forecastobjectOptional

        The forecast worker.

        Same fields as PlanStepTimes.

      • eurobjectOptional

        With eur: true, the EUR fits once a chunk holds the eur step.

        Same fields as PlanStepTimes.

      • chainobjectOptional

        With depletion_chain applied, each wave pass's work in its steps: the parents' extension, the production pass, the re-forecast and, with eur: true, its EUR fits. chunks counts passes.

        Same fields as PlanStepTimes.

    • waitobjectRequired

      How long each timed chunk and wave pass waited to enter its steps, all of them together: for another chunk or pass to leave a step and, for spacing, for room for its wells on the server.

      Same fields as PlanStepTimes.

Conditional requests 304 Unchanged since the ETag in If-None-Match.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

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

Shared errors400401403500503What they mean