Describe a model set
One model set and its dataset's extent.
Describe a model set
/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.
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_setstringRequiredpattern ^[a-z0-9][a-z0-9-]{0,62}$
A model set's id, from GET /model-sets;
defaultunless the server retired it.
Query parameters
includestringOptionalAny 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:gridwhen 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.
idstringRequiredpattern ^[a-z0-9][a-z0-9-]{0,62}$
The set's id, as
model_settakes it.labelstringRequiredA name to show.
basinstring or nullRequiredThe basin the set covers.
publisherstring or nullRequiredWho published the set; null for the default set.
defaultbooleanRequiredTrue for the set that answers without
model_set.statusstringRequiredready: loaded; loading: loading now; idle: loads on first use; unavailable: the last load failed (
errorsays why; tried again after 60 s)."ready""loading""idle""unavailable"errorstring or nullRequiredWhy the set is unavailable; null otherwise.
modelsobjectRequiredThe model number per stream the set serves, as GET /models lists them under this set.
ShowHide 3 child fields
oilstringOptionalOil model number.
gasstringOptionalGas model number.
waterstringOptionalWater model number.
streamsarray of stringsRequiredat least 1 items
The streams the set serves, in oil, gas, water order.
"oil""gas""water"stream_labelsobjectRequiredA 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 hasnovi_condensateand nonovi_oil. Known without loading the set.ShowHide 1 child field
oilstringOptionalWhat the oil slot holds.
"condensate"
sourceobject or nullRequiredWhere the set comes from, as the publisher names it (dataset, dataset_id, build_num and the like); null when unknown.
datasetobjectRequiredThe set's dataset.
ShowHide 5 child fields
well_countintegerRequiredExisting wells in the set.
bboxarray of numbersRequired4 items
Extent of the wells as [west, south, east, north].
as_ofstring or nullRequiredFormat
dateLatest production date.
basinstring or nullRequiredRegion, as the wells name it.
subbasinstring or nullRequiredBasin within the region, as the wells name it.
Show all 20 fields
model_typestring or nullOptionalWith 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 nullOptionalWith 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_countintegerRequiredThe set's wells, as GET /dataset well_count.
training_wellsinteger or nullRequiredDistinct 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 nullRequiredDistinct 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_countintegerRequiredFormations with wells or grids, as GET /formations lists them.
target_zone_countintegerRequiredFormations GET /formations?include=target marks target.
as_ofstring or nullRequiredFormat
dateLatest production date, as GET /dataset as_of.
forecast_daysintegerRequiredThe 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 nullRequiredDistinct input features across the set's oil, gas and water models; null when the server doesn't know its models' features.
catalogobject or nullOptionalWith 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
sourcestringRequiredat least 1 characters
The catalog source.
reportstringRequiredat least 1 characters
The basin report name, as the catalog lists it; an entry covers the set's own build.
publishedstringRequiredFormat
dateThe report publication date.
vintagestringRequiredpattern ^\d{4}-(0[1-9]|1[0-2])$
The month of the set's build, YYYY-MM, as include=vintage gives it.
statusstringRequiredThe catalog entry publication status.
"published"datasetstring or nullRequiredat least 1 characters
The dataset named by the catalog, or null when it does not name one.
accuracyobjectRequiredPublished oil and gas accuracy when reported.
ShowHide 2 child fields
oilobjectOptionalPublished 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 nullRequiredThe 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 nullRequiredThe 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.
gasobjectOptionalPublished stream accuracy from the catalog, expressed as fractions.
Same fields as StreamAccuracy.
notesstring or nullRequiredat least 1 characters
Curator notes, or null when there are none.
frameobjectOptionalWith 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
lengthstringRequiredLateral length, TVD and spacing distances in the set's data and models; the API answers in ft.
"ft""m"fluid_per_lengthstringRequiredCompletion 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_lengthstringRequiredProppant 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"productionobjectRequiredProduction volumes in the set's data and its models' targets.
ShowHide 3 child fields
oilstringRequiredOil volumes, the oil model's target among them; the API answers in bbl.
"bbl""m3"gasstringRequiredGas volumes (e3m3 is thousands of m3); the API answers in mcf.
"mcf""e3m3"waterstringRequiredWater volumes; the API answers in bbl.
"bbl""m3"
grid_lengthstringRequiredStructure-depth and thickness grid values; the API answers in ft.
"ft""m"
vintagestring or nullOptionalpattern ^\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-220731is2026-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_samplingstringOptionalWith include=subsurface_sampling: where the set reads its subsurface grids at a well:
BOTTOM_HOLE,SURFACE_HOLE, orMIDPOINT(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_locationsays (GET /subsurfaceconfig.params), as its training did; any other readsMIDPOINT. 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_labelsstringOptionalWith include=formation_labels:
gridfor a set the server's release file marks as labelled from its own structure grids, with a depth pack: POST /tvd-estimates bounds astructure_gridestimate, 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 nullOptionalWith 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
originstringRequiredrelease: 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 aforkorlocal; one that reads only a release file servesreleaseentries."release""fork""local"sha256stringRequiredpattern ^[0-9a-f]{64}$
A digest of
pins. A stored plan records the digest it started on, and resuming it under another fails it.pinsobjectRequiredEach 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 nullRequiredA fork's: what the release this server runs carries for the id; null for
releaseandlocal.ShowHide 2 child fields
sha256stringRequiredpattern ^[0-9a-f]{64}$
The digest of the release entry's pins.
differsobjectRequiredEach pin the release gives otherwise, as the release gives it; null where the release has none.
fork_ofobject or nullRequiredA fork's: the release's pins when the fork was made; null for a fork from before forks were stamped, and for
releaseandlocal.ShowHide 1 child field
sha256stringRequiredpattern ^[0-9a-f]{64}$
The digest of those pins.
behindboolean or nullRequiredA fork's: true when the release's pins moved since the fork was made; null without
fork_of.
Errors
| Status | When |
|---|---|
| 404 | No such well, grid, plan or route. |
Shared errors400401403500503What they mean