Skip to content
Developers
Get an API token

Describe a model set

One model set and its dataset's extent.

Describe a model set

GET/model-sets/{model_set}

One model set and its dataset's extent. This loads the set when it isn't loaded yet, so the first call can take a while.

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

include adds what GET /model-sets adds for each set (see the parameter); staff send include=pins for what it is served from.

What a set is

A dataset (wells, production, subsurface grids, spacing) with oil, gas and water models, or some of them. default is the base dataset; the others are published sets the release file pins, loaded on first use (status idle, then loading) and checked against their manifest. A set that failed to load is unavailable with an error, and is tried again a minute later.

Streams

A set's forecasts, plans, explanations, bands, EUR, type curves and exports carry only its streams; BOE counts an unserved oil or gas as 0. Naming another stream (in decline, eur_water, an export's streams or columns, a type curve, drivers, stats, a wells sort or a comparison metric) is a 400 invalid_argument listing the served ones in details.allowed. Economics prices only served streams (condensate in the oil slot at the oil price and differential); on a set serving neither oil nor gas, economics, drivers and ARIES are 400s.

The default set

A server may answer requests without model_set from a published set (GET /model-sets default names it); model_set=default still reaches the base dataset. A server may also retire default: then it isn't listed, GET /model-sets/default is a 404 and model_set=default is a 400 naming the set answering instead.

Tenant sets

An environment's own set may be scoped to tenants: staff and those tenants' users see it, and to anyone else it is an unknown id.

Errors

A set that can't load is a 503 with the reason. An unknown id is a 404, as is default on a server that retired it.

Parameters

Path parameters

  • model_setstringRequired

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

    A model set's id, from GET /model-sets; default unless the server retired it.

Query parameters

  • includestringOptional

    Any of these, comma-separated or repeated, each once; any other value is a 400 with details.field include.

    • model_type: how the set's models were built: causal, standard or null.
    • facts: figures about the set's data and models.
    • catalog: the set's curated catalog entry, or null.
    • frame: the units the set's own data and models are in.
    • vintage: the month of the set's build, YYYY-MM, or null.
    • subsurface_sampling: where the set's grids are read at a well.
    • formation_labels: grid when the set's formations come from its own structure grids.
    • pins (staff only, else a 403): what the set's entry is served from.

Responses

200 OK

The model set.

  • idstringRequired

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

    The set's id, as model_set takes it.

  • labelstringRequired

    A name to show.

  • basinstring or nullRequired

    The basin the set covers.

  • publisherstring or nullRequired

    Who published the set; null for the default set.

  • defaultbooleanRequired

    True for the set that answers without model_set.

  • statusstringRequired

    ready: loaded; loading: loading now; idle: loads on first use; unavailable: the last load failed (error says why; tried again after 60 s).

    "ready""loading""idle""unavailable"
  • errorstring or nullRequired

    Why the set is unavailable; null otherwise.

  • modelsobjectRequired

    The model number per stream the set serves, as GET /models lists them under this set.

    ShowHide 3 child fields
    • oilstringOptional

      Oil model number.

    • gasstringOptional

      Gas model number.

    • waterstringOptional

      Water model number.

  • streamsarray of stringsRequired

    at least 1 items

    The streams the set serves, in oil, gas, water order.

    "oil""gas""water"
  • stream_labelsobjectRequired

    A stream's label where it isn't the stream's name, as condensate in the oil slot; empty when every stream is its own name. On a set labelled {"oil": "condensate"} its oil forecasts, exports and model inputs are condensate, under the oil name, and so is its own wells' oil production when its dataset has novi_condensate and no novi_oil. Known without loading the set.

    ShowHide 1 child field
    • oilstringOptional

      What the oil slot holds.

      "condensate"
  • sourceobject or nullRequired

    Where the set comes from, as the publisher names it (dataset, dataset_id, build_num and the like); null when unknown.

  • datasetobjectRequired

    The set's dataset.

    ShowHide 5 child fields
    • well_countintegerRequired

      Existing wells in the set.

    • bboxarray of numbersRequired

      4 items

      Extent of the wells as [west, south, east, north].

    • as_ofstring or nullRequired

      Format date

      Latest production date.

    • basinstring or nullRequired

      Region, as the wells name it.

    • subbasinstring or nullRequired

      Basin within the region, as the wells name it.

Show all 20 fields
  • model_typestring or nullOptional

    With include=model_type: causal for a causal, counterfactual model build (as Novi Causal Intel sets are), standard for a standard build, or null when the server doesn't say. The base dataset's (id: default) comes from the server's configuration, a published set's from its release file.

    "causal""standard"
  • factsobject or nullOptional

    With include=facts: figures about the set's data and models; null until the set has loaded once, or when its figures couldn't be computed (retried on a later request). A server restarted on the same disk answers with the figures it last computed for the same set build until the set loads.

    ShowHide 8 child fields
    • well_countintegerRequired

      The set's wells, as GET /dataset well_count.

    • training_wellsinteger or nullRequired

      Distinct wells in the train split of the set's stored model predictions, as GET /models/{model_num}/evaluation splits them; null when the set stores none for that split.

    • holdout_wellsinteger or nullRequired

      Distinct wells in the holdout split of the set's stored model predictions, as GET /models/{model_num}/evaluation splits them; null when the set stores none for that split.

    • formation_countintegerRequired

      Formations with wells or grids, as GET /formations lists them.

    • target_zone_countintegerRequired

      Formations GET /formations?include=target marks target.

    • as_ofstring or nullRequired

      Format date

      Latest production date, as GET /dataset as_of.

    • forecast_daysintegerRequired

      The largest ip_day any of the set's served models forecasts (GET /models ip_days); GET /dataset ip_days when the models aren't listed.

    • feature_countinteger or nullRequired

      Distinct input features across the set's oil, gas and water models; null when the server doesn't know its models' features.

  • catalogobject or nullOptional

    With include=catalog: the curated basin report catalog entry; null for the base dataset (id: default) and for sets the catalog has no entry for.

    ShowHide 8 child fields
    • sourcestringRequired

      at least 1 characters

      The catalog source.

    • reportstringRequired

      at least 1 characters

      The basin report name, as the catalog lists it; an entry covers the set's own build.

    • publishedstringRequired

      Format date

      The report publication date.

    • vintagestringRequired

      pattern ^\d{4}-(0[1-9]|1[0-2])$

      The month of the set's build, YYYY-MM, as include=vintage gives it.

    • statusstringRequired

      The catalog entry publication status.

      "published"
    • datasetstring or nullRequired

      at least 1 characters

      The dataset named by the catalog, or null when it does not name one.

    • accuracyobjectRequired

      Published oil and gas accuracy when reported.

      ShowHide 2 child fields
      • oilobjectOptional

        Published stream accuracy from the catalog, expressed as fractions.

        ShowHide 4 child fields
        • mape_ip90number or nullRequired

          ≥ 0

          The catalog's MAPE at IP90, as a fraction (0.172 is 17.2%); null when the catalog doesn't report it.

        • mape_ip1080number or nullRequired

          ≥ 0

          The catalog's MAPE at IP1080, as a fraction; null when the catalog doesn't report it.

        • ape_ip90number or nullRequired

          The catalog's APE at IP90: signed average percentage error from Novi's published report, as a fraction; can be negative. Null when the catalog doesn't report it.

        • ape_ip1080number or nullRequired

          The catalog's APE at IP1080: signed average percentage error from Novi's published report, as a fraction; can be negative. Null when the catalog doesn't report it.

      • gasobjectOptional

        Published stream accuracy from the catalog, expressed as fractions.

        Same fields as StreamAccuracy.

    • notesstring or nullRequired

      at least 1 characters

      Curator notes, or null when there are none.

  • frameobjectOptional

    With include=frame: the units the set's own data and models are in. For reference only: every quantity it names is already in the API's units wherever this API answers it, so don't convert it; grid inputs it names no unit for, such as HCPV and pressure, are in the set's own units. The base dataset (id: default) and sets that declare no frame are in the API's units.

    ShowHide 5 child fields
    • lengthstringRequired

      Lateral length, TVD and spacing distances in the set's data and models; the API answers in ft.

      "ft""m"
    • fluid_per_lengthstringRequired

      Completion fluid per lateral length; the API answers in bbl/ft, and total fluid in bbl (the set's in bbl, gal or m3 to match).

      "bbl/ft""gal/ft""m3/m"
    • proppant_per_lengthstringRequired

      Proppant per lateral length; the API answers in lb/ft, and total proppant in lb (the set's in lb, kg or t to match).

      "lb/ft""kg/m""t/m"
    • productionobjectRequired

      Production volumes in the set's data and its models' targets.

      ShowHide 3 child fields
      • oilstringRequired

        Oil volumes, the oil model's target among them; the API answers in bbl.

        "bbl""m3"
      • gasstringRequired

        Gas volumes (e3m3 is thousands of m3); the API answers in mcf.

        "mcf""e3m3"
      • waterstringRequired

        Water volumes; the API answers in bbl.

        "bbl""m3"
    • grid_lengthstringRequired

      Structure-depth and thickness grid values; the API answers in ft.

      "ft""m"
  • vintagestring or nullOptional

    pattern ^\d{4}-(0[1-9]|1[0-2])$

    With include=vintage: the month of the Model Engine build the set's data and models come from, YYYY-MM, read from source.build_num (B20260929-220731 is 2026-09). Name a set by its basin and this month; it is the same kind of date for every set, and known before the set loads. Null when the source names no build.

  • subsurface_samplingstringOptional

    With include=subsurface_sampling: where the set reads its subsurface grids at a well: BOTTOM_HOLE, SURFACE_HOLE, or MIDPOINT (both, averaged).

    It applies to planned and drawn wells' model inputs, GET /subsurface/sample and GET /wells/{key}/subsurface. A set the release file marks to follow its subsurface config reads where its grid_sampling_location says (GET /subsurface config.params), as its training did; any other reads MIDPOINT. Left out until such a set has loaded (GET /model-sets/{model_set} loads it), and for a set without a subsurface model. Whatever it is, landings and TVD estimates use the formation top averaged over surface and bottom hole, and POST /gun-barrels its own sampling.

    "BOTTOM_HOLE""SURFACE_HOLE""MIDPOINT"
  • formation_labelsstringOptional

    With include=formation_labels: grid for a set the server's release file marks as labelled from its own structure grids, with a depth pack: POST /tvd-estimates bounds a structure_grid estimate, and POST /gun-barrels and GET /wells/{key}/subsurface draw a header TVD outside its formation, a foot inside the nearer edge. Left out otherwise. Known without loading the set.

    "grid"
  • pinsobject or nullOptional

    With include=pins (staff only): what the set is served from, as this server loaded it; null for the base dataset (id: default).

    ShowHide 6 child fields
    • originstringRequired

      release: the entry the server's release carries; fork: this environment's own entry for an id the release carries; local: this environment's own entry for an id it doesn't. A server that reads its table without a selection serves every row as stored, each a fork or local; one that reads only a release file serves release entries.

      "release""fork""local"
    • sha256stringRequired

      pattern ^[0-9a-f]{64}$

      A digest of pins. A stored plan records the digest it started on, and resuming it under another fails it.

    • pinsobjectRequired

      Each key of the entry that names its files or how they're read, when the entry has it: manifest_sha256, versioned, models, frame, depth, analogs, analog_shap, distribution, pdp_extended, bands, subsurface_sampling, formation_labels, stream_labels.

    • releaseobject or nullRequired

      A fork's: what the release this server runs carries for the id; null for release and local.

      ShowHide 2 child fields
      • sha256stringRequired

        pattern ^[0-9a-f]{64}$

        The digest of the release entry's pins.

      • differsobjectRequired

        Each pin the release gives otherwise, as the release gives it; null where the release has none.

    • fork_ofobject or nullRequired

      A fork's: the release's pins when the fork was made; null for a fork from before forks were stamped, and for release and local.

      ShowHide 1 child field
      • sha256stringRequired

        pattern ^[0-9a-f]{64}$

        The digest of those pins.

    • behindboolean or nullRequired

      A fork's: true when the release's pins moved since the fork was made; null without fork_of.

Errors

StatusWhen
404

No such well, grid, plan or route.

Shared errors400401403500503What they mean