Skip to content
Developers
Get an API token

List the model sets

The model sets this server can serve, with each one's status: the set answering without model_set first, then default (unless retired), then the release file's sets in order.

List the model sets

GET/model-sets

The model sets this server can serve, with each one's status: the set answering without model_set first, then default (unless retired), then the release file's sets in order. It never loads a set. Send a set's id as model_set on any dataset-scoped operation.

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

include adds more about each set (see the parameter). Staff send include=pins for what each set is served from: the release, this environment's fork of it, or its own set.

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.

Parameters

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

Responses

200 OK

The model sets.

  • defaultstringRequired

    The id of the set that answers without model_set: default (the base dataset), or the published set the server answers from instead.

  • model_setsarray of objectsRequired

    Every model set: the one that answers without model_set first, then the others, default (unless the server retired it) before the release file's sets in its order.

    ShowHide 19 child fields in each item
    • 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.

    • 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"
    Show all 19 fields
    • 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

Shared errors400401403500What they mean