Skip to content
Developers
Get an API token

List formations

Formations, top to bottom, with well counts and the subsurface grid for each rock property.

List formations

GET/formations

Formations, top to bottom, with well counts and the subsurface grid for each rock property. Model evaluation, baselines and plan stats group formations in this order.

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

By the median TVD of their wells, then name (those without one last); formations in the set's rock column (the one POST /gun-barrels draws) are then re-ordered by it among the places they hold.

  • Others keep their place; formations on one surface keep their median TVD order.
  • A column formation without a median TVD follows the one before it in the column (or, first, precedes the one after it); if none has one, nothing moves.
  • Without a column (no structure grids, or it can't be built), the order is by median TVD; if a set with structure grids can't build it, the answer is Cache-Control no-store and the next call tries again.
Targets

include=target marks the formations to plan or draw a well in.

Parameters

Query parameters

  • includestringOptional

    target adds target to each formation: true for one with wells and Novi subsurface grids that the served models were trained in (the Formation schema states the rule), a zone to plan or draw a well in. Any other value is a 400 with details.field include.

    "target"
  • 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

Formations.

  • formationsarray of objectsRequired

    Formations, top to bottom.

    ShowHide 8 child fields in each item
    • namestringRequired

      Name as stored and as inputs take it.

    • labelstringRequired

      Display name.

    • well_countintegerRequired

      Wells landed in it.

    • median_tvd_ftinteger or nullRequired

      Median TVD of its wells, ft.

    • median_lateral_ftinteger or nullRequired

      Median lateral length of its wells, ft.

    • gridsobjectRequired

      Grid feature name per rock property.

    • has_gridsbooleanRequired

      Whether it has subsurface grids.

    • targetbooleanOptional

      With include=target: true for a formation the models were trained in that has wells and grids. Use it for planning and well pickers; keep every formation in legends, filters and existing-well displays.

      Precisely: well_count above 0, has_grids true, and a novi_formation level (GET /models inputs) of every served model that lists those levels; wells and grids alone when none does. A forecast in a formation the models weren't trained in comes back with checks.unknown_formation.

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

Errors

Shared errors400401403500503What they mean