Skip to content
Developers
Get an API token

Get an async forecast

An async forecast: its status and, once done, result (the body POST /forecasts answers without async) or, once failed, error.

Get an async forecast

GET/forecasts/{id}

An async forecast: its status and, once done, result (the body POST /forecasts answers without async) or, once failed, error.

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

While running it answers with Retry-After: 1; send wait instead of polling. A finished job carries an ETag; send it as If-None-Match for a 304.

Scope

Any model set's job answers without model_set. Jobs are kept an hour after they finish (POST /forecasts says where); an unknown, expired or other-tenant id is a 404, as is a job on a set scoped to other tenants.

Parameters

Path parameters

  • idstringRequired

    Format uuid

    Forecast job id from POST /forecasts with async: true.

Query parameters

  • waitintegerOptional

    ≥ 1, ≤ 25

    Use this instead of polling: on a running forecast, the answer is held until it finishes, 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.

Responses

200 OK

The forecast job.

  • idstringRequired

    Format uuid

    Forecast job id.

  • statusstringRequired

    running, then done or error.

    "running""done""error"
  • created_atstringRequired

    Format date-time

    When it was requested.

  • finished_atstring or nullRequired

    Format date-time

    When it finished or failed.

  • secondsnumberRequired

    Run time so far, or in total once finished.

  • resultobject or nullRequired

    Once done, the body POST /forecasts answers with without async; null otherwise.

    ShowHide 9 child fields
    • pdpbooleanRequired

      Whether existing wells were in spacing.

    • designsarray of objectsRequired

      The completion designs, as run.

      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"
    • wellsarray of objectsRequired

      Wells, in request order; with summary: true, as plan summaries.

      ShowHide 2 variants

      One of

      • ForecastWells array of objects

        Forecast wells.

        at least 1 items

        • indexintegerRequired

          ≥ 0

          Position of the well in the request.

        • keystringRequired

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

        • labelstringRequired

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

        • inputsobjectRequired

          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.

            ShowHide 3 child fields
            • length_ftnumberRequired

              ≥ 0, ≤ 1000000

              The typed length, ft.

            • heel[number, number]Required

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

            • bhl[number, number]Required

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

          • landing_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_ftintegerRequired

          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.

        • estimatesobjectRequired

          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 objectsRequired

          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.

              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.

            • designintegerRequired

              ≥ 0

              The design, as its index in designs.

            • errorstringRequired

              Why the well has no forecast.

        • spacingobjectRequired

          Spacing.

          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.

          • neighborsarray of objectsRequired

            Neighbors, closest first.

            ShowHide 19 child fields in each item
            • neighborstringRequired

              Neighbor wellbore key, or DRAWN-<index> for another drawn well.

            • positionstringRequired

              lateral, stack or stagger.

            • well_namestring or nullOptional

              Neighbor name.

            • operatorstring or nullOptional

              Neighbor operator.

            • formationstring or nullOptional

              Neighbor formation.

            • first_prodstring or nullOptional

              Format date

              Neighbor first production.

            • heel_lonnumber or nullOptional

              Neighbor heel longitude.

            • heel_latnumber or nullOptional

              Neighbor heel latitude.

            • bhl_lonnumber or nullOptional

              Neighbor bottom hole longitude.

            • bhl_latnumber or nullOptional

              Neighbor bottom hole latitude.

            • conestring or nullOptional

              Cone, as leftstaggerbelow.

            • categorystring or nullOptional

              parent or nonparent.

            Show all 19 fields
            • signedxynumber or nullOptional

              Horizontal offset, ft (+ right looking heel to toe).

            • signedtvdnumber or nullOptional

              Vertical offset, ft (+ deeper).

            • minxynumber or nullOptional

              Minimum horizontal distance, ft.

            • mintvdnumber or nullOptional

              Minimum vertical distance, ft.

            • mintangentnumber or nullOptional

              Minimum 3D distance, ft.

            • overlapnumber or nullOptional

              Fraction of the lateral the neighbor overlaps.

            • edge_datestring or nullOptional

              Format date

              Date the edge applies from.

        • featuresobject or nullRequired

          Spacing features at ip_day 1.

        • subsurfaceobjectRequired

          Subsurface values at the well (empty without a formation).

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

          "typed""measured"
        • namestringOptional

          The name the request gave the well, trimmed; only when it gave one. label doesn't change.

        • explanationsarray of objectsOptional

          With explain: true, one per design, in design order.

          ShowHide 2 variants in each item

          One of

          • Explanations per stream object

            Explanations per stream. Only the streams the model set serves (GET /model-sets streams): a set serving gas alone answers gas alone.

            • designintegerRequired

              ≥ 0

              The design, as its index in designs.

            • oilobjectOptional

              One stream model's explanation of the forecast, or why it couldn't run.

              ShowHide 2 variants

              One of

              • An explained stream object

                An explained stream.

                • model_numstringRequired

                  Model explained.

                • unitstringRequired

                  Volume unit of the contributions.

                  "bbl""mcf"
                • shaparray of objectsRequired

                  SHAP per ip_day, ascending.

                  ShowHide 6 child fields in each item
                  • ip_dayintegerRequired

                    Days since first production.

                  • expected_valuenumber or nullRequired

                    The model's average forecast at this ip_day (its baseline).

                  • valuesobjectRequired

                    Contribution of each feature (non-zero only), in the stream's unit; expected_value plus these approximates the forecast, exactly only where the model's SHAP is additive (residual says how far it is). With explain_top / top, the largest ones and (other), the sum of the rest.

                  • inputsobjectOptional

                    With explain_inputs (POST /forecasts) or inputs=true (plan well): the value of each feature values lists (not (other)) as the model read it in this ip_day's model row. Numbers are unrounded, in the feature's unit (GET /models/{model_num} lists each input with its training range); categories such as novi_formation are strings; null where the row had none.

                  • forecastnumber or nullOptional

                    With residual=true (plan well) or explain_residual (POST /forecasts): the forecast served at this ip_day for this design, in the stream's unit, the same number GET /plans/{id}/wells/{index} serves there (on POST /forecasts, the well's forecasts[d] value before ip_days cuts it); null where none is served.

                  • residualnumber or nullOptional

                    With residual=true or explain_residual: forecast − expected_value − the sum of values (of the uncut row, whatever top keeps), unrounded: the part of the forecast the SHAP values don't attribute. Null when forecast or expected_value is null.

                • contributing_wellsarray of objectsRequired

                  Training wells sharing the forecast's tree leaves, heaviest first (top 25, or explain_top / top). On a causal model set (GET /model-sets?include=model_type), they are the training wells sharing the leaves its baseline (associative) model's prediction used, weighted before the completion effect is applied. Empty when the model's fit has no tree weights: SHAP still explains the forecast.

                  ShowHide 10 child fields in each item
                  • keystringRequired

                    Wellbore key; GET /wells/{key} has its details.

                  • weightnumberRequired

                    ≥ 0, ≤ 1

                    Share of the forecast's tree weight.

                  • well_namestring or nullRequired

                    Well name.

                  • operatorstring or nullRequired

                    Operator.

                  • formationstring or nullRequired

                    Formation.

                  • first_prodstring or nullRequired

                    Format date

                    First production date.

                  • heel_lonnumber or nullRequired

                    Heel longitude.

                  • heel_latnumber or nullRequired

                    Heel latitude.

                  • bhl_lonnumber or nullRequired

                    Bottom hole longitude.

                  • bhl_latnumber or nullRequired

                    Bottom hole latitude.

                • other_weightnumberRequired

                  ≥ 0, ≤ 1

                  Weight of every other training well (1 minus the listed weights); 1 when the fit has no tree weights and contributing_wells is empty.

                • weighted_wellsinteger or nullOptional

                  ≥ 0

                  With weight_counts or explain_weight_counts: training wells with nonzero weight, of which contributing_wells lists the heaviest; null when the fit has no tree weights or the model worker sent no counts for it, 0 when every weight is 0.

                • effective_wellsnumber or nullOptional

                  ≥ 1

                  With weight_counts or explain_weight_counts: the effective number of training wells the weight rests on, 1/Σw² over every training well's weight (weights sum to 1), to 0.001. It equals weighted_wells when the weight is spread evenly and nears 1 when one well carries it; null when the fit has no tree weights, the model worker sent no counts for it or every weight is 0.

                • weights_errorstringOptional

                  With weight_counts or explain_weight_counts, when the fit has no tree weights: why, so weighted_wells and effective_wells are null; also when the model worker sent no counts for the fit.

                • comparisonsarray of objectsOptional

                  With compare or explain_compare: one per reference, in the order asked.

                  ShowHide 2 variants in each item

                  One of

                  • A comparison object

                    A comparison.

                    • referencestringRequired

                      The reference.

                      "formation""dataset""analogs"
                    • formationstring or nullRequired

                      With formation, the formation the reference covers; null for dataset; with analogs, this well's.

                    • labelstringRequired

                      The reference in words, as Typical Wolfcamp A well.

                    • sourcestringRequired

                      The population the reference's mean SHAP is over, in words, as "mean SHAP over the WOLFCAMP A wells of the existing wells the model explained (…), per ip_day".

                    • rowsarray of objectsRequired

                      One per SHAP row (one with ip_day).

                      ShowHide 5 child fields in each item
                      • ip_dayintegerRequired

                        Days since first production.

                      • wellsintegerRequired

                        ≥ 0

                        Reference wells at this ip_day.

                      • valuenumber or nullRequired

                        The reference wells' average model forecast here as SHAP gives it: their mean expected_value plus their mean contributions, in the stream's unit; with no stored mean expected_value, this well's expected_value plus their mean contributions (start_from says which). Null with fewer than 5 wells.

                      • valuesobjectRequired

                        This well's contribution minus the reference's mean contribution, by feature, in the stream's unit. value plus these is this well's expected_value plus its SHAP values, which approximates its forecast.

                        • (baseline), when it rounds to non-zero: this well's expected_value less the reference wells' mean, which SHAP assigns to no input. In models that scale by lateral length it is mostly this well's lateral against theirs.
                        • Add the SHAP row's residual for the forecast.
                        • With top, the largest feature differences and (other), plus (baseline), which top never counts or folds.
                      • start_fromstringOptional

                        Where value starts: reference, the reference wells' stored mean expected_value; well, this well's own expected_value, where no mean is stored (values then has no (baseline)). Only on a row with a value.

                        "reference""well"
                    • keysarray of stringsOptional

                      With analogs only: the wells averaged, nearest first, the first 15 (or fewer) of the stream's analogs list.

                  • No comparison object

                    No comparison.

                    • referencestringRequired

                      The reference.

                      "formation""dataset""analogs"
                    • errorstringRequired

                      Why there is no baseline, as the model has no baseline for DEAN.

                • analog_spreadobjectOptional

                  With spread or explain_spread: what the contributing wells actually produced, scaled to this lateral. For a fit without tree weights, {error} with the model's reason.

                  ShowHide 2 variants

                  One of

                  • A spread object

                    A spread.

                    • basisstringRequired

                      What the spread is of, in words.

                    • lateral_length_ftintegerRequired

                      This well's lateral, ft: every contributing well is scaled to it.

                    • wells_consideredintegerRequired

                      ≥ 0

                      Contributing wells taken (the 50 heaviest).

                    • min_wellsintegerRequired

                      ≥ 1

                      Fewest wells for quantiles.

                    • rowsarray of objectsRequired

                      One per ip_day of the SHAP rows.

                      ShowHide 7 child fields in each item
                      • ip_dayintegerRequired

                        Days since first production.

                      • wellsintegerRequired

                        ≥ 0

                        Contributing wells whose production reached this ip_day.

                      • q10number or nullRequired

                        10th percentile of their scaled cumulatives, the low end; null with fewer than min_wells.

                      • q50number or nullRequired

                        Median; null with fewer than min_wells.

                      • q90number or nullRequired

                        90th percentile, the high end; null with fewer than min_wells.

                      • forecaststring or nullRequired

                        Where the served forecast at this ip_day falls against q10 to q90; null without quantiles or a served forecast.

                        "below""within""above"
                      • driverobject or nullOptional

                        With driver=true or explain_driver: the input that moves the forecast furthest the way forecast points; null when it is within or null, or when no input moves it that way.

                        ShowHide 3 child fields
                        • featurestringRequired

                          The model input, as novi_spacing_parent_daysonline; GET /models/{model_num} lists them.

                        • valuenumberRequired

                          Its contribution in the stream's unit, rounded to 0.001: negative when the flag is below, positive when above. Against the formation's typical well with reference formation, else the raw SHAP value.

                        • referencestringRequired

                          What the contribution is measured against: formation, the typical well of this well's formation at this ip_day (its mean SHAP over at least 5 wells, as compare=formation); model, the model's average well (the raw SHAP value).

                          "formation""model"
                  • No spread object

                    No spread.

                    • errorstringRequired

                      Why there is no spread.

                • analogsobjectOptional

                  With analogs or explain_analogs: the model's analog wells for this forecast and, when their measured coverage passes the gate, their spread; for fits with or without tree weights.

                  ShowHide 2 variants

                  One of

                  • The model analogs object

                    The model analogs.

                    • methodstringRequired

                      How they were chosen: two stages, hard filters then the distance over standard scores weighted by the model's mean |SHAP|, unless analog_weights is present, then by those weights for the inputs it names.

                      "shap_weighted"
                    • notestringRequired

                      Always "Analog spread, not the model's uncertainty".

                    • basisstringRequired

                      Who they are, in words: the filters, how many wells passed them and the ip_day of the distance.

                    • formationstringRequired

                      The formation they share with this well.

                    • childboolean or nullRequired

                      This well's parent (false) or child (true) status, which they share; null when its spacing features don't say, and then both count.

                    • lateral_band_pctinteger or nullRequired

                      How far their laterals may be from this well's, %: 25, widened to 50 then 100 until 5 wells pass; null when fewer pass even at 100, and then any lateral counts.

                      2550100
                    • candidatesintegerRequired

                      ≥ 0

                      Training wells that passed the filters; the nearest 50 are listed.

                    • weightsarray of objectsRequired

                      Every numeric model input, heaviest first.

                      ShowHide 3 child fields in each item
                      • featurestringRequired

                        A numeric model input.

                      • weightnumberRequired

                        ≥ 0, ≤ 1

                        Its share of the distance: the model's mean |SHAP| for it at its last ip_day, over the wells the build explained, or with analog_weights the share the distance used; they sum to 1. Formation is a filter, not a weight.

                      • model_weightnumberOptional

                        ≥ 0, ≤ 1

                        With analog_weights: the model's own weight for it, as weight is without them.

                    • wellsarray of objectsRequired

                      up to 50 items

                      Up to 50, nearest first (ties by key); top doesn't cut them.

                      ShowHide 22 child fields in each item
                      • keystringRequired

                        Wellbore key; GET /wells/{key} has its details.

                      • distancenumberRequired

                        ≥ 0

                        Its distance from this forecast in the model's weighted standard scores; 0 is the same inputs.

                      • well_namestring or nullRequired

                        Well name.

                      • operatorstring or nullRequired

                        Operator.

                      • formationstring or nullRequired

                        Formation.

                      • first_prodstring or nullRequired

                        Format date

                        First production date.

                      • lateral_lengthnumber or nullRequired

                        Lateral length, ft.

                      • heel_lonnumber or nullRequired

                        Heel longitude.

                      • heel_latnumber or nullRequired

                        Heel latitude.

                      • bhl_lonnumber or nullRequired

                        Bottom hole longitude.

                      • bhl_latnumber or nullRequired

                        Bottom hole latitude.

                      • cum_oil_360number or nullOptional

                        With analogs_detail: its actual cumulative oil at ip_day 360, bbl, unscaled; null when it hasn't produced that long.

                      Show all 22 fields
                      • cum_oil_720number or nullOptional

                        With analogs_detail: its actual cumulative oil at ip_day 720, bbl, unscaled; null when it hasn't produced that long.

                      • cum_oil_1080number or nullOptional

                        With analogs_detail: its actual cumulative oil at ip_day 1080, bbl, unscaled; null when it hasn't produced that long.

                      • cum_gas_360number or nullOptional

                        With analogs_detail: its actual cumulative gas at ip_day 360, mcf, unscaled; null when it hasn't produced that long.

                      • cum_gas_720number or nullOptional

                        With analogs_detail: its actual cumulative gas at ip_day 720, mcf, unscaled; null when it hasn't produced that long.

                      • cum_gas_1080number or nullOptional

                        With analogs_detail: its actual cumulative gas at ip_day 1080, mcf, unscaled; null when it hasn't produced that long.

                      • cum_oil_lifenumber or nullOptional

                        With analogs_detail: its cumulative oil to date, bbl.

                      • cum_gas_lifenumber or nullOptional

                        With analogs_detail: its cumulative gas to date, mcf.

                      • eur_oilnumber or nullOptional

                        With analogs_detail: its oil EUR, bbl, from the decline fit on its actual cumulative oil at every 30-day ip_day it has produced (analogs.eur); null when it can't be fit.

                        Null when the well lacks production at any 30-day ip_day from 30 to 360 (its first 12 months), has a history longer than eur_years, or the fit failed, and when the EUR is below its cumulative to date or not above its last 30-day cumulative (a flat extension, kept only after 90 days without production).

                      • eur_gasnumber or nullOptional

                        With analogs_detail: its gas EUR, mcf, as eur_oil is fit.

                      • inputsobjectOptional

                        With analogs_detail: the model's raw inputs for this well, in weights order.

                    • coverageobject or nullRequired

                      How often this model's analog spread held held-out wells' actual production, measured once when the index was built; null when the build has no held-out wells with production.

                      ShowHide 7 child fields
                      • ip_dayintegerRequired

                        The ip_day measured: the model's last one that enough held-out wells reach with production.

                      • kintegerRequired

                        Analogs per held-out well, as here.

                      • nominalnumberRequired

                        The share q10 to q90 would hold if it were a calibrated 80% interval.

                      • measurednumber or nullRequired

                        The share of held-out wells whose actual production at ip_day fell within their own analogs' q10 to q90, each against the training wells alone; to 0.001.

                      • wellsintegerRequired

                        ≥ 0

                        Held-out wells measured (each with at least 5 analogs with production at ip_day).

                      • gateobjectRequired

                        What the spread must pass to be shown.

                        ShowHide 3 child fields
                        • minnumberRequired

                          Lowest measured share shown.

                        • maxnumberRequired

                          Highest measured share shown.

                        • wellsintegerRequired

                          Fewest held-out wells measured.

                      • shownbooleanRequired

                        Whether measured and wells pass the gate, so spread is given; with analog_weights, only when the wells listed are the ones the model's weights list, as coverage was measured with those.

                    • spreadobjectRequired

                      With coverage.shown, q10, q50 and q90 of these wells' actual cumulatives, each scaled to this well's lateral, as analog_spread: an analog spread, not the model's uncertainty.

                      {error} instead:

                      • without coverage.shown, saying what was measured;
                      • with fewer than 5 analogs listed (candidates under 5), whatever coverage says, saying how many training wells passed the filters;
                      • with analog_weights, unless the wells listed are the ones the model's weights list, since coverage was measured with the model's weights.

                      Same fields as AnalogSpread.

                    • analog_weightsobjectOptional

                      With analog_weights, when it names some of this model's inputs: the weights sent for them, as sent; the distance then used weights, these shares with the rest shared by the model's other inputs, or these rescaled to 1 when nothing takes the rest. Absent otherwise.

                    • inputsobjectOptional

                      With analogs_detail: this forecast's own inputs, as each well's, so a table can put this well first.

                    • eurobjectOptional

                      With analogs_detail: how the wells' eur_oil and eur_gas were fit, or why there are none.

                      ShowHide 2 variants

                      One of

                      • The fit object

                        The fit.

                        • basisstringRequired

                          In words: the fit, the curves it ran on, the settings' source, what an analog needs to get an EUR (as ModelAnalogWell eur_oil says), how many got one and, by reason, how many didn't.

                        • declineobjectRequired

                          The decline settings used: each well's own once a layer below the plan reaches any well with a setting other than water; else a plan's own when it was made with eur: true, a forecast's decline with eur: true, else GET /dataset eur.defaults.

                          ShowHide 8 child fields
                          • eur_yearsobjectRequired

                          • terminal_declineobjectRequired

                          • b_minobjectRequired

                          • b_maxobjectRequired

                          • oilobjectOptional

                            Same fields as StreamDecline, nested.

                          • gasobjectOptional

                            Same fields as StreamDecline, nested.

                          • waterobjectOptional

                            Same fields as StreamDecline, nested.

                          • per_wellobjectOptional

                        • fittedobjectRequired

                          How many of the listed analogs got an EUR, per stream.

                          ShowHide 2 child fields
                          • oilintegerRequired

                            ≥ 0

                            Analogs with an eur_oil.

                          • gasintegerRequired

                            ≥ 0

                            Analogs with an eur_gas.

                      • No EUR object

                        No EUR.

                        • errorstringRequired

                          Why there is no EUR: the server has none (as eur: true answers 503), or the fit failed.

                  • No analogs object

                    No analogs.

                    • errorstringRequired

                      Why there are none, as the dataset has no analog index.

              • A stream that failed object

                A stream that failed.

                • errorstringRequired

                  Why this stream has no explanation.

            • gasobjectOptional

              One stream model's explanation of the forecast, or why it couldn't run.

              Same fields as StreamExplanation.

            • waterobjectOptional

              One stream model's explanation of the forecast, or why it couldn't run.

              Same fields as StreamExplanation.

          • No explanation object

            No explanation.

            • designintegerRequired

              ≥ 0

              The design, as its index in designs.

            • errorstringRequired

              Why there is no explanation (no forecast).

        • scored_inputsarray of objectsOptional

          Only with include=scored_inputs on GET /plans/{id}/wells/{index}, never on POST /forecasts: what the models scored, one entry per design, in design order; a design with no model rows has nulls.

          • Unlike features (the spacing features at ip_day 1), these are the inputs at a day the models score, with each design's completions. Other days' values: GET /plans/{id}/wells/{index}/explanations/{design}?inputs=true, for the inputs that day's SHAP row lists.
          • On a set with several models, the first served stream's model's rows (oil, else gas, else water).
          ShowHide 3 child fields in each item
          • designintegerRequired

            The design's position in the plan's designs, from 0.

          • ip_dayinteger or nullRequired

            The first model row's ip_day, the day values is at. Null with no model rows.

          • valuesobject or nullRequired

            Each model input's value in that row, by feature name, in API units. Null with no model rows. A null inside means the input had no number or text in that row.

      • ForecastWellSummaries array of objects

        With summary: true, plan summaries.

        at least 1 items

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

          Same fields as WellInputEcho.

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

          Same fields as DesignEstimates.

        • forecastsarray of objectsOptional

          One forecast per design, in design order.

          Same fields as DesignForecast.

        • spacingobjectOptional

          Spacing summary.

          ShowHide 2 child fields
          • nodeobjectRequired

            The drawn well's spacing node.

            Same fields as DesignNode.

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

      Step times, ms. A forecast whose wells, designs, pdp, til dates, EUR settings and bands match a request running now, or one answered earlier today (UTC) and still kept, shows 0 for the steps it didn't run; explain, explain_top, ip_days, summary, band_eur, totals and boe don't matter. Its total is its own.

      ShowHide 8 child fields
      • estimateintegerRequired

        TVD estimates.

      • subsurfaceintegerRequired

        Subsurface interpolation.

      • spacingintegerRequired

        Spacing worker.

      • calcintegerRequired

        Spacing feature worker.

      • forecastintegerRequired

        Oil, gas and water models, every design.

      • detailsintegerRequired

        Neighbor details.

      • totalintegerRequired

        Whole request.

      • explainintegerOptional

        Explanations, with explain: true.

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

    • declineobjectOptional

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

      Same fields as Decline.

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

    • totalsarray of objectsOptional

      With totals: true: one per design, or per scenario and design, as GET /plans/{id} gives them for the same wells.

      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.

            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.

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

  • errorobject or nullRequired

    Once failed, the error POST /forecasts would have answered with (a 500's message, internal error, names no request id); null otherwise.

    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.

  • linksobjectRequired

    Related URLs.

    ShowHide 1 child field
    • selfstringRequired

      This job.

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

Errors

StatusWhen
404

No such well, grid, plan or route.

Shared errors400401403500503What they mean