Skip to content
Developers
Get an API token

Explain a plan well

Why a done plan's well forecasts what it does under one design, from the model rows the plan kept: per stream, SHAP per ip_day and the top 25 training wells by tree weight, with their header details.

Explain a plan well

GET/plans/{id}/wells/{index}/explanations/{design}

Why a done plan's well forecasts what it does under one design, from the model rows the plan kept: per stream, SHAP per ip_day and the top 25 training wells by tree weight, with their header details.

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

expected_value, the model's average, plus values by feature approximates the forecast, exactly only where the model's SHAP is additive. Formation's one-hot columns are summed into one.

Options

top and ip_day cut the answer; compare, spread, analogs (with analogs_detail and analog_weights), inputs, residual, driver and weight_counts add to it, each as its parameter says; format=csv downloads the analogs as a table. spread comes from a new explanation each time, not the one the plan keeps.

Computing and caching

The explanation is computed on the first request, its streams in parallel, and kept with the plan. A forecast worker answers one request at a time, so that request waits behind a running plan. The answer carries an ETag; send it as If-None-Match for a 304.

Parameters

Path parameters

  • idstringRequired

    Format uuid

    Plan id from POST /plans.

  • indexintegerRequired

    ≥ 0

    The well's position in the plan, from 0.

  • designintegerRequired

    ≥ 0, ≤ 9

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

Query parameters

  • topintegerOptional

    ≥ 1, ≤ 50

    How many features per SHAP row and contributing wells to keep, 1 to 50.

    It keeps the largest features (by absolute contribution) and heaviest wells. Default: all features, 25 wells.

    The features cut are summed into one (other) entry (never a feature name; left out when nothing is cut), and the wells cut add to other_weight. A row's contributions still sum to the uncut row's (null contributions are left out), and the response keeps its shape with fewer entries; with residual, each row's forecast and residual are the uncut row's.

  • ip_dayintegerOptional

    ≥ 1

    Only this ip_day's SHAP row in each stream, for "why at 1 year" without every day: one of the ip_days in the explanation's shap rows, which are GET /dataset ip_days. Without it, every ip_day.

    Another value is a 400 with them in details.allowed; a value that isn't digits is refused before the explanation is computed. With top, the row is picked first and then cut. contributing_wells and other_weight are one list per stream, not per ip_day, so they are the same with or without it. A design with no forecast to explain has no rows, so any ip_day is a 400 there: ask without it to read why.

  • comparestringOptional

    The references to compare with, comma-separated: formation, dataset, analogs.

    Each explained stream gains comparisons, one per reference.

    formation is the wells the model explained in this well's formation (a typical Wolfcamp A well, say), dataset every well it explained. At each ip_day, values holds, by feature, this well's SHAP contribution minus the reference wells' mean: read an entry as "compared with a typical Wolfcamp A well, this input adds (or removes) N". It rearranges the same SHAP values, so it can't contradict them.

    • value is the reference wells' mean expected_value plus their mean contributions (start_from reference), or this well's own expected_value plus theirs where no mean is stored (start_from well).
    • (baseline) in values is this well's expected_value less the reference mean: mostly its lateral length against theirs, in models that scale by lateral. It comes only with start_from reference, not when it rounds to 0, and never counts toward top or (other).
    • value plus values is this well's expected_value plus its SHAP values (each rounded to 0.001); the SHAP row's residual is what they leave out of the forecast.
    • wells counts the reference at that ip_day (long ip_days rest on older wells); under 5, value is null, values empty and start_from absent.
    • top folds small differences into (other); ip_day keeps one row. A reference without a baseline (a formation the model never saw) is {reference, error}; GET /models/{model_num}/baselines lists them.

    analogs, on model sets that store their analogs' SHAP, averages this forecast's own first 15 analogs per stream the same way (a missing feature counts 0), in the analogs list's ranking (reweighed by analog_weights when sent), whether or not analogs is asked; analogs itself comes only when asked. Its keys name them, nearest first. It is {reference, error} when the dataset has no analog index, the set stores no analog SHAP or it can't be read (tried again after a minute), the analogs can't be ranked, or the model has no training analogs of this forecast in its formation.

  • spreadbooleanOptional

    Default false

    true adds analog_spread to each explained stream.

    An analog spread, not the model's uncertainty: for the model's own P10/P90, send bands: true.

    It is the 10th, 50th and 90th percentiles (q10 the low end) of what the model's 50 heaviest contributing training wells actually produced by each ip_day, each scaled to this well's lateral length (wells without one are left out). Only wells whose production reached the ip_day count (wells); under 5, the quantiles are null. contributing_wells still lists 25, or top when that is fewer, and other_weight is re-summed from 50 weights, so it can differ in the last digit.

    forecast says whether the served forecast (as GET /plans/{id}/wells/{index} serves it; on POST /forecasts, forecasts[d] before ip_days cuts it) is below, within or above q10 to q90, compared before rounding; null without quantiles or a served value. driver names the input that moves it there.

  • analogsbooleanOptional

    Default false

    true adds analogs to each explained stream, from the explanation the plan keeps (no new model call).

    The model's own analog wells for this forecast, from its training wells, each stream from its own model.

    They are the 50 nearest wells of the same formation and parent/child status whose lateral is within 25% of this well's (widened to 50%, then 100%, until 5 pass), by distance over the model's inputs at its last ip_day, standard-scored and weighted by mean |SHAP| (weights). wells lists them nearest first, whatever top.

    spread is the 10th, 50th and 90th percentiles of what they produced by ip_day, scaled to this well's lateral, as analog_spread: an analog spread, not the model's uncertainty. Unless coverage passes, it is {error} with the measured figure (the wells are still listed): on the model's held-out wells, q10 to q90 must have held 70% to 90% of actual production at coverage.ip_day (nominal 80%) over at least 300 wells. coverage.measured is always given.

    Their type curve: POST /wells/typecurve with their keys as wells, normalize_lateral_ft = spread.lateral_length_ft and quantiles: [10, 50, 90] matches spread while that lateral is within 100 to 20,000 ft.

    A dataset without an analog index (the default dataset), or a set before its index is installed, answers analogs: {error} with the reason; analog_spread is unchanged.

  • inputsbooleanOptional

    Default false

    true adds inputs to each SHAP row: the value of each feature its values lists (not (other)), as the model read it in that ip_day's model row, so a driver reads with its input ("proppant 2,800 lb/ft adds X bbl"). Goes with ip_day and top; with format=csv it changes nothing.

  • residualbooleanOptional

    Default false

    true adds forecast and residual to each SHAP row; show the residual beside the drivers ("not attributed") so the parts add up to the forecast.

    forecast is the forecast served at that ip_day for this design, as GET /plans/{id}/wells/{index} serves it (on POST /forecasts, forecasts[d] before ip_days cuts it), or null. residual = forecast − expected_value − the sum of values, unrounded, on the uncut row, so top and ip_day don't change it; null when either is null. On a causal model set (GET /model-sets?include=model_type) SHAP values approximate the treatment effect, so the residual can be large. With format=csv it changes nothing.

  • driverbooleanOptional

    Default false

    true (400 without spread=true or analogs=true) adds driver to every analog spread row: the model input that moves this forecast furthest the way the row's forecast flag points.

    It is {feature, value, reference}: with below, the most negative contribution; with above, the most positive; in the stream's unit to 0.001, from the uncut SHAP row. With reference formation, a contribution is this well's SHAP value minus the typical well's of its formation at that ip_day (the compare=formation baseline, when it has at least 5 wells there; a missing feature counts 0); otherwise model, the raw SHAP value. Null when the flag is within or null, or no input moves it that way (a contribution rounding to 0 counts as none). comparisons still come only with compare.

  • weight_countsbooleanOptional

    Default false

    true adds weighted_wells and effective_wells to each explained stream: how many training wells carry weight, and how concentrated it is.

    They count every training well, not only those contributing_wells lists: check them before saying a forecast rests on the listed wells. Both are null, with weights_error, for a fit without tree weights or counts; all-zero weights give weighted_wells 0 and effective_wells null. With format=csv it changes nothing.

  • analogs_detailbooleanOptional

    Default false

    true (400 without analogs=true) adds each analog's production, EURs and model inputs to analogs.wells.

    • cum_oil_360, cum_oil_720, cum_oil_1080, cum_gas_360, cum_gas_720, cum_gas_1080: actual cumulative oil and gas (bbl, mcf) at 1, 2 and 3 years of 30-day months, unscaled; null where it hasn't produced that long. cum_oil_life, cum_gas_life: to date.
    • eur_oil, eur_gas: EUR (bbl, mcf) from Novi's type-curve decline fit, as eur: true runs it, on its actual cumulative at every 30-day ip_day (its last 400), unscaled.
    • inputs: the model's raw inputs for it at the distance's ip_day (basis), in weights order, null where missing.

    An EUR is null when the fit fails, without production at every 30-day ip_day from 30 to 360, with a history longer than eur_years, or below the cumulative to date. One not above its last 30-day cumulative is a flat extension, kept only for an analog without production in its last 90 days (Novi's dry-well rule). An EUR from under 3 years of production (a null cum_oil_1080 or cum_gas_1080) is less certain.

    analogs.inputs gives this forecast's own inputs the same way. analogs.eur gives the basis, the decline settings and how many got each EUR (fitted); it is {error} when the server has no EUR or the fit failed or took over 30 s. The settings are each well's own once a layer below the plan reaches any well with a setting other than water; else the plan's (made with eur: true), the forecast's decline, or GET /dataset eur.defaults.

    Each analog is fit once per request; the worker keeps recent fits, so a repeat is cheaper. Nothing else in the answer changes.

  • formatstringOptional

    Default "json"

    csv (with analogs=true, else 400) downloads the analogs as a CSV table instead of the JSON explanation; json is the default.

    The file is text/csv, an attachment named plan-well-<n>-design-<m>-analogs-<YYYY-MM-DD>.csv (positions from 1, the server's UTC day; analogs-weighted with analog_weights), without an ETag.

    Per stream with analogs, oil, gas then water: a row for this well (rank 0, well_name "This well", its formation, lateral, inputs and eur_basis: analogs.eur.basis or its error), then one per analog, nearest first (rank 1 to 50). A stream whose analogs or explanation is {error} adds no rows (the JSON answer says why), so the table can be its header alone.

    Columns: stream, rank, key, distance, well_name, operator, formation, first_prod, lateral_length, heel_lon, heel_lat, bhl_lon, bhl_lat, the cumulatives and EURs of analogs_detail, eur_basis (with analog_weights, then analogs_basis on rank 0 rows), then each model input by highest weight, then name; blank where a model lacks it. An input header that would repeat another gets input_ in front until unique. Text starting with =, +, -, @, a tab or a carriage return gets a leading ', so a spreadsheet doesn't run it.

    ip_day, top, compare and spread are checked but don't change the table.

    "json""csv"
  • analog_weightsstringOptional

    Comma-separated feature:weight pairs, as novi_lateral_length:0.4,novi_tvd:0, sent once (400 without analogs=true or when repeated); send a + (as in 1e+2) as %2B, since a bare + in a query is a space.

    Your weights for the analog distance, as shares on the scale of analogs.weights[].weight, one map for every stream's model. A named input takes exactly its share and the model's other inputs split the rest as the model weighs them; when nothing takes the rest, the shares sent are rescaled to sum to 1. A model with none of the names answers as without them.

    Weights are finite, from 0 (which drops an input), summing to 1 at most. A 400: a name no model in the set takes (details.allowed lists their inputs), a malformed pair, a repeated name, a negative or non-finite weight, or a sum over 1. Weights that all come to 0, or weighted inputs that don't vary across the candidates, answer analogs: {error}.

    A reweighted stream gives analogs.analog_weights (yours), weights (the distance's, heaviest first, each with its model_weight) and basis, naming the inputs you weighted; method stays shap_weighted. Its spread is {error} unless it lists the wells the model's weights list, since coverage (still given) was measured with those. The filters don't change; analogs_detail and format=csv follow the reweighted analogs. Without an analog index, names aren't checked.

  • 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 explanation; with format=csv, the analogs table.

Returns text/csv.

One of

  • PlanWellExplanationStreams object

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

    • indexintegerRequired

      ≥ 0

      The well's position in the plan.

    • labelstringRequired

      Display name, as Plan well 2.

    • designintegerRequired

      ≥ 0

      The design, as its index in designs.

    • namestringOptional

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

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

  • PlanWellExplanationError object

    No explanation.

    • indexintegerRequired

      ≥ 0

      The well's position in the plan.

    • labelstringRequired

      Display name, as Plan well 2.

    • designintegerRequired

      ≥ 0

      The design, as its index in designs.

    • errorstringRequired

      Why there is no explanation (no forecast).

    • namestringOptional

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

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.

502

A model worker returned an error.

Shared errors400401403500503What they mean