Skip to content
Developers
Get an API token

List the forecast models

The forecast model behind each stream, each as GET /models/{model_num} describes it.

List the forecast models

GET/models

The forecast model behind each stream, each as GET /models/{model_num} describes it.

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

include=groups adds each input's catalog group, include=distribution its training distribution, and include=served_fit_wells the distinct wells the served all fit was trained on.

The card

What a stream's forecast model is and what it saw.

Inputs

inputs are the training ranges forecast checks compare against: p01 and p99 over training rows, without the no-neighbor fill value. A design input is in checks.out_of_range only when it is more than 5% of p99 minus p01 outside them; neighbors' production features (novi_spacing_sum_prior_, novi_spacing_delgados_p) outside them, with no margin, go to checks.context instead.

Accuracy

The served all fit was refit on the holdout wells too. Held-out accuracy is the pre-refit train fit's (GET /models/{model_num}/evaluation; evaluation.available and reason say whether there is one), and holdout.rule says how holdout wells were chosen. Cached, with an ETag; on the sample stack every figure is a sample (sample_data: true).

Parameters

Query parameters

  • includestringOptional

    groups, distribution or served_fit_wells, comma-separated or repeated, each once; any other value is a 400 with details.field include.

    groups adds each input's Intel basin report catalog group; distribution the card's distribution and each input's training distribution (five quantiles and a 20-bin histogram, or level counts); served_fit_wells the card's count.

    "groups""distribution""served_fit_wells""groups,distribution""groups,served_fit_wells""distribution,groups""distribution,served_fit_wells""served_fit_wells,groups""served_fit_wells,distribution""groups,distribution,served_fit_wells""groups,served_fit_wells,distribution""distribution,groups,served_fit_wells""distribution,served_fit_wells,groups""served_fit_wells,groups,distribution""served_fit_wells,distribution,groups"
  • 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 models, one per stream.

  • modelsarray of objectsRequired

    One per stream: oil, gas and water.

    ShowHide 17 child fields in each item
    • model_numstringRequired

      Model number, as GET /dataset models[] names it.

    • streamstringRequired

      Stream.

      "oil""gas""water"
    • targetstring or nullRequired

      Target column, as novi_oil; null when the dataset doesn't record it.

    • unitstringRequired

      Unit of its predictions.

      "bbl""mcf"
    • sample_databooleanRequired

      True when the figures come from synthetic sample data.

    • served_fitstringRequired

      The fit that serves forecasts: all, refit on training and holdout wells.

      "all"
    • trained_onstringRequired

      What the served fit saw, in words.

    • ip_daysarray of integersRequired

      ip_days the model predicts.

    • versionsobject or nullRequired

      Package versions of the fit, by package name; null when the build records none, as on the sample stack.

    • trainingobject or nullRequired

      The pre-refit train fit's training wells; null when the build doesn't record them.

      ShowHide 3 child fields
      • wellsintegerRequired

        ≥ 0

        Training wells.

      • rowsintegerRequired

        ≥ 0

        Training rows (well × ip_day).

      • first_productionobjectRequired

        First production range.

        ShowHide 2 child fields
        • fromstring or nullRequired

          Format date

          Earliest first production.

        • tostring or nullRequired

          Format date

          Latest first production.

    • holdoutobject or nullRequired

      The train fit's holdout wells; null when the build has no stored predictions.

      ShowHide 3 child fields
      • wellsintegerRequired

        ≥ 0

        Holdout wells.

      • rulestringRequired

        How they were chosen, in words.

      • first_productionobjectRequired

        First production range.

        Same fields as ModelSpan.

    • inputsarray of objectsRequired

      Each input in feature order with its training range; empty without training statistics.

      ShowHide 10 child fields in each item
      • featurestringRequired

        Model feature, as novi_lateral_length.

      • labelstringRequired

        Its display name, as Lateral length.

      • kindstringRequired

        numeric or category.

        "numeric""category"
      • p01number or nullRequired

        1st percentile over training rows, leaving out the no-neighbor value; null for a category.

      • p99number or nullRequired

        99th percentile over training rows, the same way; null for a category.

      • blank_sharenumberRequired

        ≥ 0, ≤ 1

        Share of training rows where it is blank.

      • levelsarray of strings or nullRequired

        A category's levels in training, sorted; null for a number.

      • fillnumber or nullRequired

        The features' value for no such neighbor (days online -1, distances at the spacing defaults), which p01 and p99 leave out; null when it has none.

      • groupstringOptional

        With include=groups: the input's group as Novi's Intel basin report catalog groups model features: geology, spacing, depletion (parents' prior production: novi_spacing_sum_prior_* and novi_spacing_delgados_p*, as the depletion chain reads them), completion, location, or other.

        "geology""spacing""depletion""completion""location""other"
      • distributionobject or nullOptional

        With include=distribution. Null when the card's distribution is unavailable or the model's file has no row for this input.

        ShowHide 10 child fields
        • unitstringRequired

          The input's unit (ft, lb/ft, bbl/ft, deg, fraction and so on). An empty string when the input is unitless or its unit isn't documented.

        • rowsintegerRequired

          ≥ 0

          The model's training rows (well x ip_day).

        • blankintegerRequired

          ≥ 0

          Rows that are null or NaN.

        • fillintegerRequired

          ≥ 0

          Rows holding the features' no-neighbor value. See the input's fill.

        • rangedintegerRequired

          ≥ 0

          rows - blank - fill. Only these rows enter min, max, quantiles and histogram.

        • minnumber or nullRequired

          Minimum ranged value. Null for a category or without ranged rows.

        • maxnumber or nullRequired

          Maximum ranged value. Null for a category or without ranged rows.

        • quantilesobject or nullRequired

          Null for a category or without ranged values. Compare a planned well input with these quantiles to place it in the training data.

          ShowHide 5 child fields
          • p01numberRequired

            Exact 1st percentile. Equal to the input's p01.

          • p10numberRequired

            Exact 10th percentile.

          • p50numberRequired

            Exact median.

          • p90numberRequired

            Exact 90th percentile.

          • p99numberRequired

            Exact 99th percentile. Equal to the input's p99.

        • histogramobject or nullRequired

          Null for a category or without ranged values. Add counts below a planned well input to place it in the training data.

          ShowHide 4 child fields
          • edgesarray of numbersRequired

            21 edges of 20 equal-width bins from p01 to p99. When p01 = p99 there is one bin with edges [p01, p99].

          • countsarray of integersRequired

            Items ≥ 0

            Bin i holds edges[i] <= x < edges[i+1]. The last bin also holds x = p99.

          • belowintegerRequired

            ≥ 0

            Ranged rows under p01.

          • aboveintegerRequired

            ≥ 0

            Ranged rows over p99.

        • levelsarray of objects or nullRequired

          Category counts ordered by rows descending, then level. A category has no quantiles or histogram. Null for a numeric input.

          ShowHide 2 child fields in each item
          • levelstringRequired

            Category level.

          • rowsintegerRequired

            ≥ 0

            Rows at this level.

    Show all 17 fields
    • bandsobjectRequired

      P10/P90 bands, as GET /dataset bands reports them for this stream.

      ShowHide 3 child fields
      • availablebooleanRequired

        Whether the model has a stored P10/P90 bands fit.

      • methodstring or nullRequired

        How the bands are made.

      • reasonstring or nullRequired

        Why not, when it hasn't.

    • eurobjectRequired

      EUR.

      ShowHide 1 child field
      • availablebooleanRequired

        Whether eur: true extends this stream's forecasts to EUR (oil and gas, when the server fits EUR). False for water, which takes eur_water: true.

    • evaluationobjectRequired

      Held-out accuracy.

      ShowHide 3 child fields
      • availablebooleanRequired

        Whether GET /models/{model_num}/evaluation has figures for this model.

      • reasonstring or nullRequired

        Why not, when it hasn't.

      • hrefstringRequired

        Its evaluation's path.

    • served_fit_wellsinteger or nullOptional

      ≥ 0

      With include=served_fit_wells: the distinct wells the served all fit was trained on, the training and holdout wells of the build's stored predictions with a well in both counted once; null unless the build stores predictions for both splits.

    • distributionobjectOptional

      With include=distribution.

      ShowHide 2 child fields
      • availablebooleanRequired

        Whether the training distribution was read.

      • reasonstring or nullRequired

        Why not, when it isn't available.

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

Errors

Shared errors400401403500503What they mean