Skip to content
Developers
Get an API token

Describe the dataset

The dataset's name, build and as-of date, basin, well count and extent; its forecast models per stream, with their features and ip_days; the request limits; and which streams have EUR and P10/P90 bands.

Describe the dataset

GET/dataset

The dataset's name, build and as-of date, basin, well count and extent; its forecast models per stream, with their features and ip_days; the request limits; and which streams have EUR and P10/P90 bands.

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

include adds the oil or gas stream with the larger share of first-12-month BOE, or the count of wells without a location, which GET /wells leaves out.

Parameters

Query parameters

  • includestringOptional

    primary_stream adds the stream, oil or gas, with the larger share of the dataset's first-12-month BOE, and unlocated_well_count the number of wells in well_count without a location (no longitude), which GET /wells and the map leave out; send either or both, comma-separated or repeated, each once, and any other value is a 400 with details.field include.

    "primary_stream""unlocated_well_count""primary_stream,unlocated_well_count""unlocated_well_count,primary_stream"
  • 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 dataset.

  • namestring or nullRequired

    Dataset name.

  • buildstring or nullRequired

    Dataset build.

  • sample_databooleanRequired

    True when the data is synthetic.

  • basinstring or nullRequired

    Basin, as Midland.

  • regionstring or nullRequired

    Region, as Permian.

  • well_countintegerRequired

    Wells in the dataset.

  • formation_countintegerRequired

    Formations with wells or grids.

  • as_ofstring or nullRequired

    Format date

    Latest production date.

  • first_productionstring or nullRequired

    Format date

    Earliest first production.

  • bboxarray of numbersRequired

    4 items

    Extent of the wells: west, south, east, north.

  • modelsarray of objectsRequired

    Forecast model per stream.

    ShowHide 5 child fields in each item
    • streamstringRequired

      Stream.

      "oil""gas""water"
    • model_numstringRequired

      Model number.

    • targetstringRequired

      Target column.

    • featuresarray of stringsRequired

      Model input features.

    • ip_daysarray of integersRequired

      ip_days the model predicts.

  • ip_daysarray of integersRequired

    ip_days forecasts are reported at.

Show all 20 fields
  • spacingobjectRequired

    Spacing config.

    ShowHide 1 child field
    • search_radius_ftnumberRequired

      Radius the spacing step searches for neighbors, ft.

  • subsurfaceobject or nullRequired

    Subsurface config.

    ShowHide 4 child fields
    • methodstring or nullRequired

      Interpolation method.

    • gridsintegerRequired

      Grids.

    • distance_from_gridsnumberRequired

      A point the set reads (its subsurface_sampling in GET /model-sets) farther than this from a grid is left out of that grid's value.

    • distance_from_grids_unitsstringRequired

      Units of distance_from_grids.

  • limitsobjectRequired

    Request limits.

    ShowHide 3 child fields
    • forecast_wellsintegerRequired

      Most wells per POST /forecasts.

    • plan_wellsintegerRequired

      Most forecasts (wells × designs) per POST /plans: the most wells with one design.

    • plan_unfinished_forecastsintegerRequired

      Most forecasts (wells × designs) one caller may have in queued or running plans once one is unfinished; POST /plans answers 429 past it.

  • eurobjectRequired

    EUR on this server.

    ShowHide 6 child fields
    • availablebooleanRequired

      Whether this server fits EUR (the forecast worker can run Novi's decline fit); eur: true answers 503 when false.

    • methodstring or nullRequired

      Novi's type-curve decline fit; null when unavailable.

    • defaultsobjectRequired

      Decline fit settings used. oil and gas, when present, are the settings each stream was fit with; without them, both were fit with these. water, when present, is the echo of eur_water.

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

      Allowed ranges, inclusive; b_min must also be below b_max.

      ShowHide 4 child fields
      • eur_yearsobjectRequired

        eur_years range.

        ShowHide 2 child fields
        • minnumberRequired

          Lowest allowed.

        • maxnumberRequired

          Highest allowed.

      • terminal_declineobjectRequired

        terminal_decline range.

        ShowHide 2 child fields
        • minnumberRequired

          Lowest allowed.

        • maxnumberRequired

          Highest allowed.

      • b_minobjectRequired

        b_min range.

        ShowHide 2 child fields
        • minnumberRequired

          Lowest allowed.

        • maxnumberRequired

          Highest allowed.

      • b_maxobjectRequired

        b_max range.

        ShowHide 2 child fields
        • minnumberRequired

          Lowest allowed.

        • maxnumberRequired

          Highest allowed.

    • streamsarray of stringsRequired

      Streams that get an EUR.

      "oil""gas"
    • versionsobject or nullRequired

      Library versions the forecast worker fits with, by package name; null on the sample stack.

  • bandsobjectRequired

    P10/P90 bands on this server.

    ShowHide 5 child fields
    • availablebooleanRequired

      Whether any stream has bands here (its model has a stored bands fit); bands: true answers 503 when false.

    • methodstring or nullRequired

      Novi's predrill bands (split conformal, safe variant); null when unavailable.

    • percentiles[integer, integer]Required

      Bands' percentiles: p10 is the low curve and p90 the high one (Novi's convention).

    • streamsarray of stringsRequired

      Streams whose model has bands, among those the set serves; the others answer each forecast with a bands error.

      "oil""gas""water"
    • reasonstring or nullRequired

      Why bands are unavailable, or which streams have none and why; null when every stream has them.

  • depletion_chainobjectRequired

    The depletion chain on this server.

    ShowHide 3 child fields
    • availablebooleanRequired

      Whether a served model reads neighbors' production, so the depletion chain changes forecasts. When true, POST /plans chains a dated plan unless it sends depletion_chain: false; when false, every plan runs without it, also one sent with depletion_chain: true.

    • featuresarray of stringsRequired

      The models' features that read neighbors' production: the spacing features novi_spacing_sum_prior_* and novi_spacing_delgados_p*.

    • neighbor_productionstringRequired

      Where existing (PDP) parents' production comes from, for every forecast and plan on this set: history is their production to the dataset's as_of, held flat after; extended continues it with Novi's production forecast for each existing well past its history.

      "history""extended"
  • primary_streamstring or nullOptional

    With include=primary_stream: oil or gas, whichever has the larger share of this model set's first-12-month BOE, summed over every well with a 12-month oil or gas volume, a missing stream counting as 0; null when the dataset has none at all; ties oil. Oil bbl is compared with gas mcf / 6 (GET /conventions boe); water is never primary.

    "oil""gas"
  • unlocated_well_countintegerOptional

    ≥ 0

    With include=unlocated_well_count: how many of well_count wells have no location (no longitude). GET /wells lists only wells with a location, so it leaves these out, and no map or spatial filter places them. 0 when every well has one.

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

Errors

Shared errors400401403500503What they mean